Learning to Read Code

One of my junior co-workers asked me the other day for advice. They had inherited modules written by someone who'd recently left the company, & they were conflicted over whether to make drastic changes to the style & formatting, or just try harder to understand the code as it was so that the task at hand could be done.

   "How do you understand someone else's code without making it look like you're used to?"

Even if you have style guides, style checkers, automatic formatting, etc, there will be minor variations in style that can make code more in line with your own thinking, or small things that stand out as being "unreadable" that can taint the whole module. The classic examples are too much or too little comments, or too much or too little white-space. Note that these two, in particular, go both ways. It's a matter of personal preference.

No matter how much you work on Clean Code, a la Bob Martin, there will be tricks or approaches to a problem (even patterns) that you pick up in your career that are obvious to you, but will look strange & unreadable to someone else. Being aware that it might happen goes a long way to making your software more maintainable.

If you equate reading code to reading a book, for any given publishing market, the audience is essentially homogenous. As an author, you might aim for a geography & an age group (maybe a gender) or else a special interest. You more or less assume that anyone in that broad category will be able to read your book, & be able to understand what you have written - to appreciate it. The reality is that people always have favourite authors - a style or topics that they are more drawn to. Most people will also have authors that they just don't like - their style jars with them.

Reading someone else's code is exactly the same as reading a book that you didn't write. Some people write code that more people easily understand. Some write code that is targeted to a very specific niche audience - sometimes numbering one.

If you want your code to be maintainable, follow Uncle Bob's rules for Clean Code to get most of the way, but above all, remember that you are an author with an audience of coders who will read your work later.

If you want to approach other people's code to garner understanding - to maintain it - always remember that the author wasn't necessarily writing in your style, but you have to read it anyway, so look deeper for how they have gone about writing the code, how they are telling the story. The story is in there, because the code probably worked at some point. It is your job, as a maintainer, to find that story & understand it.

I can't teach you how, because I've achieved it through experience - voracious reading. There are no short-cuts to getting better at maintaining code. It just takes a lot more practice & a lot less wishing that the novel before you was as easy to comprehend as a Mills & Boone.

Technology Wars

A little while back, I started looking at a few different development languages. Each had its benefits & applications, which is why they came into existence in the first place. But, & here's what annoyed me, they each carried with them a justification that they were "superior" to any prior language, tossing about spurious claims about the limitations of some against the strengths of their favourite.

I say "spurious claims", because they sounded quite ridiculous to me, & I suspect anyone with real experience in the language under attack would agree. Sure, there is a level of comfort in the familiar, just as there is a daring excitement in taking on the new, but to then ignore these prime considerations & label one language as deficient because it can't do well a particular thing that a new language was designed specifically for, does seem to be drawing a long bow for justifying change.

Let me pick one such language, & I guarantee you'll be hard-pressed to work out which one it is:

•  It’s Perfect For Web Technologies
•  Saves Money
•  Saves Time
•  Active & Helpful Community
• Project not Handcuffed (to the original implementors)
• Build your own Plug & Play Apps
• The Big Players Use It
• You can use it too! (Personal & Professional use)

There you have it, the perfect language. Everyone should use this for web-based development. I'm sold - but which one is it? I suspect many CEOs would take this immediately, too.

This is what used to be referred to as a religious war. Once upon a time, there were only two or three great languages (religions), but now there is a proliferation. That's fine; I'm tolerant.


However, I have found the same sort of arguments creeping into other technologies within a development environment. The best revision control, continuous integration, IDE, etc.

Really - & honestly - it doesn't matter what the particular choice made is, but what matters is that you embrace that choice & follow through. You have to find the best way to use the technology at hand, become proficient, have effective processes in place that understand that technology, & continually review your processes & get feedback to learn from its use, innovate, & go forward.

I recently convinced management to standardise a team on IntelliJ to develop Java. I did this with minimal experience of IntelliJ, but with the knowledge that the team was spread across three IDEs! That was an intolerable situation that led to inefficiencies & basic time-wasting trying to get things to work in different environments, or supporting different technologies simultaneously.

Now, that team shares tips, fixes problems once (someone upgrades, tests, then gives the OK for the team to upgrade), finds plugins useful for everyone, & basically works together on the same problem from the same base level. I believe that the same could have been achieved using Eclipse or NetBeans with a similar effort - as long as it was only the one IDE.

Similarly, some complain that Jira "doesn't do what they want". That's just showing an inability to master a very simple & effective (but feature-rich) issue control system. There may be better ones, but Jira is, industry-wide, considered one of the good ones. Master the tech, don't let it master you.

Wrapping up, there are always good & bad choices for a technology, but there's usually a fine line between several good choices. At that point, put the religion aside & decide for the good of the team. Making a decision is what counts, not getting it perfect.

By the way, the "Eight reasons" was for Ruby.