Comments on: Comments are a sign of bad code and I am not sorry for saying it

By: M

Tue, 27 Oct 2009 17:37:55 +0000

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.

By: Billy Korando

Billy Korando — Mon, 26 Oct 2009 01:16:31 +0000

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.

By: Ben

Ben — Sun, 25 Oct 2009 22:18:45 +0000

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.

By: McBonio

McBonio — Sun, 25 Oct 2009 12:36:13 +0000

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.

By: Inside the Webb

Inside the Webb — Sat, 24 Oct 2009 19:36:22 +0000

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/

By: Developer Art

Developer Art — Fri, 23 Oct 2009 11:15:37 +0000

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.

By: Owen Fellows

Owen Fellows — Fri, 23 Oct 2009 08:47:03 +0000

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.