The most valuable tip towards writing highly legible code

As programmers/coders we all have to revisit/review/debug our own code as well as others’. Some times the code can be as large as thousands of LoC (=Lines of Code)! Large projects have a large overhead on understanding, before someone is able to add new functionality or fix a bug! Even my own projects seem somewhat incomprehensible at first, when I revisit them after a large period of time! I was always intrigued by simple solutions, but I could never form a few simple guidelines of code legibility that one could follow anywhere, anyhow, with any GUI and with any Framework!

That was before I read the recently published book “Building Maintainable Software” by Joost Visser. The title does not do the book justice. I would very much prefer the following title :
“Simple guidelines that can drive any developer to create highly legible code in any programming language!”

The book was a pleasant read. But when I finished reading it, I felt uneasy. I needed to see if the guidelines were as good as they seemed! So I gave the first principle a try. “Keep each method below the threshold of 15 LoC”. And that’s when the magic happened!

I had an opportunity to give this guideline a spin, on a hobby game project I was working on, which was not in Java but in gml (Game Maker’s own scripting language). While reviewing my code I realized that I had more than a few methods that counted at 20–30 LoC each. And I always had a feeling of uneasiness whenever I had to add more functionality after a significant anount of development pause! So I started refactoring my code, so that each method was as short as possible (less than 15 LoC). I also tried to keep each method simple and reusable, while trying to come up with good names on my methods. There was not really much difference at first. But when I started adding more functionality to the project, I realized the following :

– Revisiting my code was as simple as reading the methods name (given that its name was a good one!)

– For those methods that had less of a good naming, revisiting its code was only a matter of seconds

– My mind seemed to work faster! I had to work with a lot of functions, but that was not really a problem in the end! Because I did not spend so much time reading and re-reading code until I could get hold of it. I was simply glancing through my methods fast! Very fast! And that was the incredible part! My initial fear that partitioning my code would create some incomprehensible code was false! Incomprehensibility does not seem to come with partitioning but with large chunks of code!

Psychologists have discovered that the human mind’s working memory amounts to about seven items! So we have a buffer of seven items! The magic number 7!
Subsequently, the best tip you will probably ever get at programming is “keep your functions at about 7 LoC”. Reading the book, you will discover that there are 10 simple guidelines that will increase your code’s legibility in most situations. The first 4 guidelines are generic and they can be applied on any programming language or framework :

– Limit the length of functions to 15 LoC
— Limit “if” statements per function to no more than 4
— Do not copy code. Write reusable functions

– Keep each function’s arguments to no more than 4

Putting these guidelines to the test is the only way to find out if your code’s legibility will increase or not. Try them out and drop a comment with the results!

Further information:
1. You can find the book here.

2. You can find a review of the book here.