Source Code is for Humans

Back in the day when I was in college we used to play the ’guess the output of’ game. It involved cryptic snippets of C code and people playing compiler. It used to be a thing in those days. The stakes were high as you tried to fit in and prove yourself. Serious bragging rights were up for grabs. Here’s an example -

#include < stdio.h>

int main()

{

   int i;

   int *ptr = (int *) malloc(5 * sizeof(int));

   for (i=0; i<5; i++)

   {

       *(ptr + i) = i;

   }

   printf("%d ", *(ptr+i)+2);

}

The truth is, no one should write code like this. Software is not a one time deal that you can fire and forget. It evolves with versions and patches. It needs to be maintained long after it is released in the wild. Often by folks who didn’t write it. When (not if) the proverbial poop hits the fan, you’re on a clock to set things straight. It often involves ogling at stack traces, dumps and yes, the source code. Readability and comprehension are king.

We’re living in relative prosperity when it comes to resources at our disposal. Folks often compare the Apollo 11 computer with modern day smartphones to underscore the point. But one doesn’t have to be quite as dramatic to appreciate how far technology has come. Machines have become faster, storage is aplenty, memory no longer requires you to live in penury.

And yet a lot of programmers continue to code trying to squeeze bits out of every byte. Remember Unions in C. While I have nothing against Unions and Bitwise operators, my point is overeager optimization by the programmer is not the best use of her time.

There’s no need to worry about the source code being 10% larger due to longer symbol names, multiple files, loosely coupled objects etc. Premature optimization generally does more harm than good. Compilers are pretty smart these days, let them optimize it for you. This is not to say don’t worry about the time complexity of your code. Certainly don't use a polynomial time algorithm when logarithmic time would suffice. The point is not to worry too much about optimizing temporary variables, initialization and assignment, don’t take short cuts on class hierarchies, interfaces and such because the source code ‘looks’ bloated. Readable code goes hand in hand with good design. A well organized project structure makes it trivial to find a certain file. One shouldn’t have to guess where your logs, configuration, header files, shared objects, third party dependencies, READMEs and build artifacts live.

Intention revealing class, method and variable names go a long way in self documenting the code and help with debugging. Using natural language phrases rather than cryptic abbreviations makes reading the code a lot easier. The question to ask would be - how can we reduce the cognitive load on the programmer who’s trying to make sense of what you wrote? often with limited context.

It’s important to establish conventions and stick to them. Indentations, spacing, braces, naming are all important. Yes, conventions and processes can be annoying when overdone but chaos ensues when there are none. One needs to find a balance. Also every language is different - it’s best to follow conventions that are language specific.

Furthermore, forcing yourself to think about an appropriate class name can reveal design flaws. Maybe your class is doing too many things aka the god object. Maybe it’s not doing enough or is simply piggybacking on other classes - these anti-patterns are called feature envy and freeloader respectively. Perhaps the responsibilities are not clearly differentiated.

Same goes for project, package, library, file, methods and function names. If you have a getDimentions() method, it shouldn’t mutate dimensions. The ideas are really simple and most developers get it. It’s either the lack of discipline or the temptation to give in to an arbitrary deadline that often gets us.

The final point I want to make is about comments. They have their place and are important. But wouldn’t it be nice if the code was self documenting. There's a school of thought that believes comments shouldn’t try to describe the internal logic of a function or class because as the code undergoes revisions, the accompanying comments are seldom updated. This divergence of documentation and implementation can lead to confusion and heartache. At a minimum, treat comments and documentation as first class citizens.

Happy coding.