eduTrain

Lesson 5 / الدرس 5

Your first week in code somebody else wrote / أسبوعك الأول في كود كتبه غيرك

Nobody reads a codebase. You arrive, you are given something small, and you follow one thread through it — and the map you build that way is more useful than any tour, because it is built out of things you actually needed.

لا أحد يقرأ مستودعًا. بل تصل، ويُعطى لك شيء صغير، فتتبع خيطًا واحدًا خلاله — والخريطة التي تبنيها هكذا أنفع من أي جولة، لأنها مبنية من أشياء احتجتها فعلًا.

The instinct on day one is to read everything and understand the architecture before touching anything. It does not work, and the reason is that a codebase is not written to be read in order — it is a hundred decisions taken at different times, and without a reason to care about any particular one, none of them stick.

Follow one request all the way through

  1. Get it running locally first. Before anything else, and however long it takes. Every hour spent here is repaid daily, and the notes you make while doing it are the onboarding document the next person will not have either.
  2. Pick one page and find the route that serves it. Then the thing the route calls, then where the data comes from, then the template. One thread, end to end. You now know the shape of every other page.
  3. Change something small and watch it break. Deliberately. Knowing what fails when you edit a thing tells you what depends on it faster than reading ever will.
  4. Read the tests for the thing you are about to touch. They are the only documentation that fails when it goes out of date, which is why they are worth more than a wiki page written two years ago.

Reading git as archaeology 

# Who last touched this line, and in which commit?
git blame src/Bookings.php

# Then read that commit in full. The message usually says why, and why
# is the thing the code cannot tell you.
git show a1b2c3d

# Everything that ever touched this file, newest first
git log --oneline -- src/Bookings.php

# When was this odd-looking condition added, and what came with it?
git log -S 'is_legacy_rate' --oneline

# blame is not blame. It is the fastest route to the person or the
# commit that can explain a line, and the answer is almost always
# "there was a reason" rather than "somebody was careless".
That last comment is worth carrying. Code that looks wrong is usually code that was right about something you do not know about yet — a customer who needed it, a bug it fixed, a deadline. The commit that introduced it will often say so in one line, and reading it before objecting saves both of you a conversation.

Check yourself / اختبر نفسك

1. Why does reading a codebase from top to bottom not work?

2. What is git blame most useful for?

3. Why not reformat a messy file in your first month?