Saturday, April 17, 2010

Why Commenting Code Is Evil...

If you never read books about good coding, I recommend warmly one of them: Clean Code. This book emphasis a lot on practices you should follow on writing your code readable.

Some of those practices may appear for some as shortsighted like the part of not commenting code. We know that commenting code is an issue of understand fairly big code bases. From my point of view NaroCAD is mostly medium code-base so can be taken (at least most of it) in mind of one developer (NaroCAD have close of 1000 classes but as you remove some "infrastructure classes", you will remain simply with much fewer classes and you can get an full overview about it).

So why is better to not comment your code? There are opinion that might be a lot of reasons why to comment your code: for example you want to know what does a function. But this can simply show simply other problems in your code like: does the function name is really right named? why does it needs an explanation of what it process (or about its arguments..). If your function name does not give an enough explanation of what it does, you should write a longer definition.

Also, some comments may be fully redundant so there is no use to get them. If you supposedly have a property: IsVisible that can be set, and can get a boolean value, what can bring your comment to make you to understand it better? 

Another point is that writing comments can take a lot of time, and as you use refactoring tools, this documentation may simply get out of context, as most refactoring tools do not propagate the documentation's comments with even very simple refactors. What is the point to get an documentation that LIE about your code?

At the end, write their comments in their understanding of the flow, or have notes about it, but largely the documentation may be not that detailed or that coherent for other reader (when do you know that your comments are reviewed by someone just to be sure that they are not only up-to-date, but to be enough conclusive to get the value of writing them!?)

There are comments really necessary? Sometimes they are. They firstly can write under which is your license which may be mandatory for some projects. Other part that I find them really useful are with associated tags: TODO, FIXME, BUG, etc. that they add value that you can follow your code flow and get real comments that are enough explanatory for someone even new in your code. 

At the end, at least for NaroCAD case (this book is about Java language but most of principles apply unchanged on C#/.NET side), splitting code in regions may create a huge difference on reading code (and works like comments but are just for separating code). C# permits automatic properties and automatic detection of the expression type (using var keyword) and using them wisely will clean up a bit your codebase. Those changes may improve on a greater margin your code clarity than commenting your code.

The bottom line of this post is just that redundancy and even worse, discrepancy of what is expected by what is actual in code can create your code longer, hard(er) to maintain and time waster. Redundancy in comments may not be an issue, if you are a lazy programmer, but sometimes you can avoid also duplicate code and useless branches by using programming by contract.

No comments: