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.