7 tips for reading others’ code with understanding (especially if you do not know the system)

Ivo Valchev

14 January 2018

So that our thoughts aren’t few and far between:

  • This article consists of a list of techniques which I have found through experience and the experiences of others
  • It primarily focuses on finding your way around web applications implementing the MVC pattern, however most tips are applicable to programming as a whole
  • These techniques will be more useful if you have prior experience with programming and your concern is more about the current language/system/setup.

Intro blah-blah

Imagine you were me: first day at work at the new workplace, given access to the web server where the company website is hosted and that is pretty much it. It is now your (sole) responsibility to maintain and develop this software according to the needs of the company you work for — you cannot go and ask the guy who wrote the code what happened. This was me a year ago.

The only thing I knew prior to this encounter was that the website backend was written in PHP. Anyway, I found out there is a Git repository and started browsing through the code and the commits. After a few minutes of reading code in a language I had never worked with before (yet alone the web framework on top of it), it gradually began to mean something, here and there it made some sense. But then it became apparent that some things don’t add up — pages are rendered at URLs that should not exist, there is functionality which is not defined anywhere in the code I was looking at. It turns out parts of the website work under the more recently deployed PHP framework, whilst others are legacy Classic ASP code — and I had programming experience in neither of these.

It was then that I realised how important it is to develop the ability to read code (even without knowing the syntax of the language it is written in) as much and as further as possible.

The nitty-gritty

At first, all you should care about is the what. What does this code do? Ignore the how and for the time being ignore the why. To get the what, you can take advantage of the following strategies:

1. Walk backwards

It would seem natural to first start exploring “the database” (or to be more precise the models of your MVC framework) to see what kind of data is stored, then move to the controllers to observe how this data is manipulated and then, if needed, study how this content gets rendered.

However my experience and that of others suggest another strategy:

Start from the actual results, I would even say take a look at the website itself, have a go with it, explore what it does so that you know what functionality to expect to see implemented in the code.

Then navigate through to the view, which chance is will reveal what kind of data is stored and to some extent in what form. From there you can go further backwards to the controller and reach the model too.

It is important to remind that you are trying to answer the “what”, not the “how”, i.e. as long as you know what actionAttachmentDownload() does, for now you shouldn’t care how exactly it does it.

This leads me to the next one, namely:

2. Explore feature by feature

Code exploration in the order mentioned above will almost certainly guarantee you learn how things work on a “feature by feature” level. You do not need to stare at the big picture as it will make the task much more difficult. Do not overcomplicate things.

3. Use grep

As dumb as it may sound, at the very beginning I found it very useful to search for actual plain text. Especially when you are dealing with a more complex system (that you know very little about), trying to find your way through endless folders, subfolders and files is quite challenging. Identify unique names which will help you locate what you are looking for and dive in. (For those unaware, grep is a command-line utility for searching plain-text)

4. Don’t trust comments. Trust code.

We often get told (or at least I do at university) to document the code with comments, even by creating specs detailing how to write the comments! I will not engage into the seemingly endless discussion about self-documenting code vs documenting code through comments (despite having my views on it). However in the cases when you are dealing with old legacy code (which was what I had to wrestle with), it is much safer to stick to the code that gets executed and not the comments, which would have been written at the time of creation and probably not updated since.

5. Expect to find garbage

In my particular case there was a lot of garbage code — functions or entire subsystems no longer in use. Companies are less likely to change their business models than their systems, therefore it is not unusual that you find the same or similar goals/functionalities achieved by using different “technologies”.

Of course bad code can be cleaned up. But it’s very expensive.

For me, it was the newer PHP-based implementation with its own database and everything on one side, and the older ASP on the other; and the existing overlap between the two. Therefore, it is helpful to expect to find garbage and bear this in mind when you are trying to figure out what code gets executed when (and if at all).

6. Write stuff down

As soon as you get your head around what a large-enough component of the code you are getting the grasp of does, it is easier to write what you have found out down than to remember it. Your focus should be on exploration. Depending on your preference, you may want to docu

7. Find the automated tests

This should probably be No.1 on your “how to read others’ code” list. Unit tests, in particular, are meant to be as simple as possible. You do not even need to look at the actual test — skimming through unit tests’ names will give you an idea of what they test, hence what the system does.

So basically…

These are tips which I found helpful when faced with the situation of having to read, understand and work on an implementation written in two languages I had never used before. These are, of course, meant to just help one get started and will in no case be sufficient in the medium- and long-terms, when advanced knowledge is required to develop functionality and code which others in turn will need to get comfortable with.

Oh by the way, this is my first article ever. I expect there to be much room for improvement and will value any feedback— if you have any, please do let me know by leaving a comment below or contacting me at me@ivovalchev.com.

Till next time. 😉