Comments are evil

I’ve just finished listening to an interesting episode of the Deep Fried Bytes podcast entitled in part “Why comments are evil”. In this episode the guest, Corey Haines (a traveling programmer living an interesting life which warrants discussion in itself), explains why he believes comments shouldn’t be the recommended practice they are often considered, and can be easily abused. Here’s a quick summary of his reasoning:

Comments are often used to explain poorly written code

Comments rot

In summary:

My thoughts

The timing of this couldn’t have been better for me. I’d spent the day working on the code for the memory efficient data list I discussed last week. I had just created 3 functions which each did around 8 different task, broken up by comments explaining what each did. Each task was only 3 – 6 lines of code, so it wasn’t an obscenely long method, but I still wasn’t sure whether to refactor or move on. After listening to the podcast I took their advice of never leaving this until later and refactored the next day.

The result:

Now I plan to impose a new coding ‘rule’ – no comments within methods.

What about comments above public methods, and at the head of classes? The podcast touched on these, saying you might want them for a framework, or for API documentation, although you shouldn’t use them in an auto doc style whereby you just replicate parameter names in comments. I have mixed thoughts on this. I agree that it seems pointless to describe well named methods and well named parameters twice, although it can be useful to detail restrictions on parameters for API documentation. I’d then like to use an automatic tool to produce this documentation to be kept from the code. Also descriptions at the head of certain classes can help explain where, when and how to use the class.

I guess my final thought is to use discretion.

Any thoughts?

4 Comments

Jack Moxley

Aghhh the world of mobile with 20 classes and a few thousand lines of code developed by a maximum of 5 people.

Try writing an enterprise level application with a minimum of 20 people and millions of lines of code without comments. For the first month it will be fine. the 2nd month will be irritating and the 3rd month you will be doing nothing but answering other peoples queries.

Comments should do 2 things.
1: Tell you what the method/class does (and not how it works)
2: mark problematic or unfinished code with TODOs (unfinished code does exist in the real world and it needs some way of maintance).

In order for this to work.
Methods should be small (200 lines is way too big)
Methods that are in effect State machines should be commentted for each state change.
Methods and Classes should be well named.

But mostly
Abstraction is not your friend, unless you need to do the same thing twice, something normally reserved for API’s.

BTW java developers have a documentation from code generator its called javadoc.

kirby.mark

Hi Jack, thanks for your thoughts.

I agree that comments can have their place, but just using them without thinking and describing everything can be a waste of time. A well named method – for example, “moveFirstItemToEndOfList”, shouldn’t need any more explanation if the context its in is obvious. They shouldn’t be crutch to write unreadable and abstract code. If you are writing easy to understand code, the rest of team should be able to just follow it. That’s the theory at least!

Keith Elder

Mark,

Thanks for lilstening to Deep Fried and thanks for taking the time to blog your experience after listening to the show. Reading your post makes the long nights of recordings and post production work worth it to know we may have helped someone.

Great read.

Thanks,

Keith Elder
http://twitter.com/keithelder

aglassman

I always try to put comments in my methods. Just because something makes sense to one person does not mean it will make sense to someone else. As a developer who has had to pick apart commet-void classes and home-grown frameworks, I jump for joy whenever the original author left even a few scraps of comments. This is especially useful when the original authors have left the company, which is quite common in IT. It is also fun to read original authors comments because you start to get a sense of their personality and thought process.

Leave a comment: