Comments are a sign of bad code and I am not sorry for saying it
In my recent article, 8 signs your code sucks, one of my signs of bad code is: “You need to use comments to explain the code.” I have since taken a lot of flak for suggesting this and I want to clarify my point and why I am not backing down.
Not javadoc - I am NOT referring to Javadoc or its equivalents in other languages. I absolutely do agree that a method or class should have accompanying documentation at its declaration stating its purpose and its inputs and/or outputs.
Comments are not bad, the code is – I'm not suggesting to forgo the use of comments, but that they are only band-aids. When you don't have time to properly write a piece of code; do it the “messy” way, write a comment and give it a TODO as a reminder to go back and fix it later.
Comments make code accessible - Code should not be written to the level of the dumbest developer, the dumbest developer should be brought to the level of the code (though I want to reiterate good code should be easily readable). If a developer is unwilling or unable to meet or at least understand the rest of the team's coding standards, then questions should be asked rather you want that developer to understand the code at all.
They are more like guidelines – When it comes to design patterns there are no rules. From day one we are taught goto statements are evil and should never be used, but there is even a time and place for them. There may be rare occasions when you have to write a comment to explain a piece of code, just like you may need to use a goto to simplify the code, but both occasions are rare and when encountered in code should be scrutinized.
Related posts:
Categories
Tag Cloud
Archives
- November 2009 (3)
- October 2009 (18)
- September 2009 (15)
October 23rd, 2009 - 03:47
I agree with your comments on comments, a lot of the time the comment simple states what the line of code is doing which is pointless as a developer should be able to work this out for themselves. I think there are exceptions though e.g. you have a procedure performs a large number of operations in a specific order defined at your design stage. This steps can be documented in the Javadoc for the method but it is worthwhile have comments to state that each step is start/finished e.g. Step 3 – Update User Record.
However saying this it would be more useful for debug and maintainance if these we log statements instead of comments. I believe in almost all cases comments can be converted to log statements which make them useful for those maintaining the system.
October 23rd, 2009 - 06:15
I personally think you’d rather write self-documented code and leave the class documentation out unless it is absolutely needed. The problem with any kind of commenting is that it is disassociated from code. It takes extra effort to synchronize comments with the code they refer to. I have seem many examples when comments were talking about something very different from the code after the code has been written und vastly updated during the next years.
October 24th, 2009 - 14:36
This is really interesting and you bring up some good points, but I’d have to say that comments really do help. I discuss this deeply on my web 2.0/programming blog http://www.insidethewebb.com/
October 25th, 2009 - 07:36
Comments, although they look untidy they serve a purpose.
One of my main clients I just make templates for and they have programmers that cant design but add their CMS code into my templates.
Without comments they would struggle to place the content as they are not designers.
October 25th, 2009 - 17:18
Perhaps you would find it easy to understand a nlp classifer, a pattern recognition algorithm or neural net implementation without comments purely based on academic papers discussing theories and trees?
Comments for complicated code are needed, badly written code can be complicated but this doesn’t mean that all comments are a sign of bad code.
October 25th, 2009 - 20:16
They are more like guidelines – When it comes to design patterns there are no rules. From day one we are taught goto statements are evil and should never be used, but there is even a time and place for them. There may be rare occasions when you have to write a comment to explain a piece of code, just like you may need to use a goto to simplify the code, but both occasions are rare and when encountered in code should be scrutinized.
October 27th, 2009 - 12:37
I agree with Ben that comments are required while writing complicated code. It definitely takes a couple of mins more time to sync up the comments with any changes that are further made in the code. But it is worth the time spent.