Why do you lose time over understanding other’s code?
Developers’ main job is about modifying code: almost all programming is done in the context of an existing code base.
Before modifying or adding anything, I need to understand what the code I’m working on is doing, who wrote it and why. So when it comes to coding the past does matter.
IEEE conducted an experiment on that matter, they cconscientiously tracked down developers over thousands of working hours. The result was pretty amazing, on average developers are spending only 5% of their time writing new code, 20% modifying the legacy code but up to 60% understanding the existing code in a project! (mind blown)
So I broke down what took so much energy… Understanding the code requires me to navigate through the code itself but also the tests and any attached piece of explanatory documentation. Despite all the good coding practices out there, it’s easy for a code to get hard to understand.
We often talk about coding good-practices to enhance code maintainability: seld-documented code, test coverage, modularity… But it’s one thing is to push for implementing good practices another is to track them and understand the impact they have on the code. In general, the practice or application of best practices is dependant on the life of the code.
- For short-lived code, we are more focused on things which will help us solve the problem initially and quickly. If you are working on a product that needs to be released in 2 weeks, or the profit margin quickly drops, focusing on solving the problem instead of maintainability is probably the right answer.
- For long-lived code, we are more concerned with practices which will help us to maintain the code and will reduce the cost of changes to the system over time. If you are working on releasing a product which has an estimated R&D time of 1 year, reducing quality at the beginning of the project will cost you more time in the end.
If your code ends up living for another 2 years, at some point you will pay the price if you don’t start following the best practices for maintainability.
I’ll focus on two aspects that often appear as the opposite when I talk with my fellow developers: self-documented code VS code documentation. Let’s the fight begin !
Seld-documented code
Definition: Code that allegedly explains itself without the need for extraneous documentation, like flowcharts, UML diagrams, process-flow state diagrams …
Developers can make use of certain coding techniques to clarify their code, simply by using the programming language’s features to our advantage. There are 3 main categories to improve a code self-documentation :
- Structural : where the structure of code or directories is used to clarify the purpose
- DRY : Don’t Repeat Yourself
- Be short and specific. A function should have only one goal and factorized when possible. However, watch out for the anti-pattern: sometimes developers separate 2–3 lines of code that will never be used anywhere else into a function for documentation purposes. Methods are created for the sole reason to document the code (and easier TDD). This results in Function Hell. The code is less readable than it was originally
- If the software is nicely divided into separate modules, I don’t have to read all hundreds of thousands of lines of code, I can quickly find a few hundred lines in a couple of modules. If we’ve put the effort into clear naming (But, then, as we all know, “There are only two hard things in Computer Science: cache invalidation and naming things.” — Phil Karlton), I can quickly understand what the various part of the code does.
- Really Obvious Code (ROC)
2. Naming related, such as function or variable naming. (Let’s remember old Phil here again)
- Don’t hesitate to rename variables, functions to make it follow the business logic
- Follow naming conventions
3. Syntax related, where we make use of (or avoid using) features of the language to clarify the code. We might avoid syntax tricks : you might be saving 2 or 3 lines of code but if the developer that comes after doesn’t get it straight it a loss of energy.
// Tricky
imTricky && doMagic();// Clear
if(imTricky) {
doMagic();
}
Making your code self documenting goes a long way to improving the maintainability of your code.
Note that self-documented code does not mean that there should be no comments, but only that there should be no unnecessary comments.
Comments in the code
Comments should never compensate for code which is not self-describing enough. Yet, it should not be an or/or matter but and/and one. Yes, make your code as much self documenting as possible, and yes, add some comments for an easier code navigation.
The most obvious case is when you work in an enterprise environment, where people are constantly sharing code and people don’t always have the time to make their code perfect, a few good comments can save tons of time and frustration. Two main reasons :
- While you may be a guru who can read through code at a glance that might not be the case for everyone. What is “self-documenting” to you, may not be to someone else…
- What is clear to me now, might not be so in a year, when I’m thinking about something completely different and need to use this part of the code again.
So, comment your code, not every line of course, but you should add a few lines explaining :
- “why” (of course)
- “what” on individual lines only when the code is complex or the purpose is unclear and it can’t be or isn’t worth simplifying further
- “what” for blocks of code to speed up comprehension and locating what you need
On-boarding a large project with hundreds of thousands of lines of code, summary comments massively increase the speed in which developers get productive.
I don’t want to waste 20 minutes per class , going back and forth between the code and the tests. In many cases I just need to know what a class or a method does and a couple of sentence of summary.
Naming your methods and classes properly, as Uncle Bob tells us, does help, but there’s a sweet spot of verbosity that cannot be expressed as a class or method name that a couple of summary sentences in a comment provide.
Easy to understand example :
//Bad code
float a, b, c; a=9.81; b=5; c= .5*a*(b^2)//Poorly commented code
const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.
// Self documented code (answering the "what")
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);//Both self-documented and commented code (answering "what" and "why")
/* compute displacement with Newton's equation x = vₒt + ½at² */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
By reading the code (including comments and documentation comments) should yield an immediate understanding of what the code does and why. If the “self-documenting” code takes longer to understand than commented code, it is not really self-documenting.
Ajouter une description
Conclusion
Because the relationship between cost and internal quality is an unusual and counter-intuitive relationship, it’s usually hard to absorb. But understanding it is critical to developing software at maximum efficiency. — Martin Fowler
Most of the time companies do see the cost of implementing those long-term maintainability good practices. However, it is much more complicated to estimate and calculate the impact of their absence.
Taking time to build modular and being explicit code saves a lot of head-scratching later on. When fast shipping and high-quality delivery is key to satisfy customers, lack of readable, simple and documented source code is a curse for software companies.
Maëliza Seymour
