Stop documenting the documentation

A while ago I got into a discussion about documentation, can documentation help a programmer to be a better programmer? My view on this is simply no. I know that this is something that is debated all over and there are these two sides, either you are cheering for code documentation or you don’t. I cheer for the latter and I will explain why.

First of all a small disclaimer, I do love documentation of architecture, APIs and all of those project artifacts, they are essential to the project. But it’s not that kind of documentation I will address here, but simply documentation of source code.

Clean up your code

So the first thing, comments is a bad thing because it excuses the developer if he or she write bad code. It tend to add acceptance for sloppiness because you can always explain what you are trying to accomplish with written comments in plain text. First of all, programming is a craft and we are craftsmen. We must act like it and try to improve ourselves. This being said, without the option of explaining yourself with comments in the code you need to focus on write good, simple and explainable code so that other developers easily can read and understand what the code is doing. A few examples;

  • The method signature shall be explaining what the method does e.g.
    public bool SaveNewCustomerToDatabase(ICustomer newCustomer)
  • Write short methods that focus on one well defined thing. If the signature can’t explain what the method does, your method is probably too long or complex and you would need to break it up into smaller ones.
  • Use meaningful variable names. Instead of using
    bool b = false;

Try
bool isConnected = false;

I strongly believe that focusing on good code instead of documenting it will help developers to be better and improve their craftsmanship.

Comment smell

Another bad thing about commenting code is that it will start to smell. We are all familiar with code smell, but comment smell is just as bad. Let me explain. Comment smell is something that will start growing alongside with the comments. The harsh truth is that in most systems where comments are used, the code will change but the comments will not. At first when the guide lines for how the code shall be written and documented is established in the beginning of the projects, the comments will be just fine. But when things start to change due to maintenance, quick fixes or sprints, more and more code will be changed without the developer changes the comments. This is comment smell, the comment describes something other than the code actually performs and that is really bad. It is bad since you can’t trust the comments in the system. If one comment is off, you can’t trust the rest. It’s just like when using unit tests, you must be able to trust them for them to be of use to you.

Message handling

I have worked in a several different kinds of projects with mature software like maintenance and system reviews. One thing that I tend to find in all those projects is message handling in the code. No, I do not talk about sending messages to a MSMQ or anything like that, but the source code files being used as a chat where developers writes comments to each other. This is among the worst comments of all since they can indicate an issue, and when you find the comment you have no idea if it is taken care of or if is still an issue. For instance, the next example is a real comment that I found and that had been in the source for over 15 years.

“1994-10-11 We have a problem here that can crash the application. I don’t have time to fix it now so someone else has to do it //Jens”

Oki? Someone else? Who and when? This is BAD! This is a perfect example of comment smell. Issues shall be handled outside of the code in a structured way using post-its, TFS, JIRA or whatever system that can be used to keep track of issues, but not the source code!

Exceptions

There are an exception after all. If you are introducing a complex algorithm in the code and it is hard to understand it, then you should comment it. But then and only then, not with trivial code.

Conclusion

Just to wrap things up, no I don’t think that documenting the source code will help you be a better programmer. In fact, documenting the source code is documenting the documentation because in my eyes, the source code itself is the documentation for the system that explains how the compiled software works!

Don’t forget, you are a craftsman, the code you write is art, it’s built by your key strokes, and don’t waste time on documentation but constantly improve your skills!

“if you can’t write good code, you should not be allowed to comment it!”