The Myth of code comments

strip-le-code-des-autres-650-finalenglish-1

During the last week of December, one of our intern at Enalean met one of its university professor. When the intern showed him his work of the first months, the very first comment of the teacher was : « Your code has no comment! ».

For me, this in an old belief I heard while I was at the university by every single teachers. This was also a big critera when our projects or practical works were evaluated. However, commenting code is a myth. A good code is a code that does not need comments.

Why having a readable code?

Code is like a living entity. Once created, it evolves, moves, is removed … In every part of its life, code is read by multiple humans. So, developers must create a code easily readable, but far more important, understandable.

This is true if you don’t want to rewrite an entire part of code, 6 months after the first implementation, to add a new functionality, or if you want to maintain it in the future.

Make a readable code, without comments

My teachers said me : « Comments are needed to explain what this piece of code does ». And I’m OK with that. We can add a comment on each line to say « add an element to the array », « assign the variable with the form value » or « return the value ».

But this has no value. If you have to explain each line or part of code, your code writing style has probably have big issues (code smell).

One of the best example is the method naming. I think that it’s better to have:

function getCollectionOfObject(array $object_ids);

instead of

/**
 * This function returns a collection of object
 */

function get(array $param);

This is the same approach for variables. A variable named $collection will be more understandable than $a or $var.

In Tuleap software codebase, I found one day the following comment: // $idx is the artifact id.
Don’t you think naming this variable $artifact_id should have be better?

Developers are also able to remove comments by creating private methods or functions. If you have for instance a big boolean condition, extract this in a private method. Explicitly saying what you are checking will improve the code readability.

Keep in mind that your code have to be easily understandable. If you add comments to increase the code readability, the developper who read it will have to read the code, then the comments, and then will have to map the code with the comments. If your code is easily comprehensible without comments, the developer will have to read it only one time, and this will make him/her more happy.

Unit tests do comment your code

keep-calm-and-unit-test

Unit tests are also a good tool to understand code. They test some behaviors. So by definition, they clearly say what the tested part of code do, is not able to do, what are its limits, etc.

Writing a complete test suite will ease the code understanding in the future for the developer who will work on that part of code, even if the developer never work on it. Unit tests will help you as an entry point when you will work for the first time on a feature or on a new project.

Ok, sometimes, comments are useful

Comments are useless. It’s not true. Adding systematically comments is useless. This is true.

It remains, sometimes, some cases where comments are valuable.

For instance, in Tuleap hudge codebase, I’m happy as a developer to see some comments, in particular, contexts. The first example I have in mind is to explain a particular behavior of en external tool used (CKEDITOR default escaping). Another example of important comment is to notify other developers when we do a specific trick in order to be compatible with all web browsers.

Conclusion

In conclude, do not write comments systematically. Spend your time and your energy writing a code readable, understandable and well tested. This will really help others.

By the way, teachers, it could be great stop hammer home that comments are mandatory and are the most important component of the code to students ­čÖé

Do no ask to comment code to students

About the Author

Agile developer

Write Your Comment

trois × un =

You may use these HTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>