A Funny Java Flavoured Look at the World

Wednesday, May 17, 2006

Should you comment code

I was recently talking to my fellow programmer and saying that I read somewhere that your code shouldn't have any comments in because it should be self explanatory.  if there is a piece of code that you deem so tricky it needs comments then you should change the code to make it easier to understand and named better.  I believe it was an Extreme Programming article I was reading with this advice.  It is an interesting thought and what is the right level of commenting in your code.
 
Personally I think it has a good ideology but in practise I don't think adding a few comments is such a bad thing but I think to many comments in the code is a definite code smell and you should refactor the code.  A lot of comments is usually found in a big long method. 
 
There are a lot of comments in the code where I work and one of the main reasons is because they don't write unit tests which takes away one level of documentation of code.  Usually you can see what a class or method should be doing by looking at the unit test and seeing what it's testing it for.  I think a decent amount of documentation should be in the JavaDoc comments.  If the code needs a lot of commenting or has a lot of commenting then I am guessing the methods are too long and it should be split up into more well named methods. 
 
I find well named methods document the code really well because if you are looking at the code with well named methods you feel as if you don't have to look in the method to see what it's doing.  I can see that sometimes you are going to need documentation if you use a lot of classes or the classes have complex hierarchies. 
 
I don't think you should get rid of comments in code, I think this is a step to far and what's the real benefit of having no comments.  I also think that every time you are thinking about putting in a comment, you should look at the code to see if you can make it more transparent because over commenting is a definite sign that the code could be refactored and made simpler.
 
 

1 Comments:

  • From the hypothesis that clear code doesn't really need comments you must not conclude that your code is clear because of the absence of comments. Such a logic is as faulty as the code will be. No kidding, I was once told that the code is so good that it doesn't need comments (whose absence I complained about) - well I think that proves clearly that the code is all but clear if you beg for comments.

    Usually I like sparse comments that point out the dangerous edges in the code. Such edges always exists and will pop up if they are rare - so you know that you have to pay even more attention there.

    Another observation is that when you encounter a large comment block somewhere in mostly uncommented code you have probably found the location of a bug. Comments like these serve as an explanation what the programmer intended to do what might well be a different thing from what is actually implemented.

    A general arguments against comments: Wrong comments do not raise a compiler or runtime error, so they are the last thing a programmer in hurry cares about

    By Anonymous Anonymous, at Wed May 17, 06:38:00 pm 2006  

Post a Comment

<< Home