Why comments in the code are not always good!
Why comments in the code are not always good!
(1) Because they are not updated.
When ever the code is changed, the comments should also be changed. But it may happen like the code is updated but not the comments which may confuse the next developer.
(2) Maintenance problem.
Highly commented code is difficult to maintain. Think of a situation where change in a line of code requires you to edit five lines of comment.
(3) They add up to the size of the file.
This is a matter of great significance if your file goes across the network. For example:
Heavily commented JavaScript file may take time to get downloaded to the client machine. This is may affect the Performance of web app.
(4) Irritating.
Think of a comment.
total = mine + your; // adding mine and your cash to calculate the total cash.
If you read a line such as this don't you feel irritated? Most of the times in line comments are useless.
(5) Using comments as the solution for bad coding style.
The method names and variable names should self explainable. It shouldn't happen like you are writing comments to make up for the in appropriate names you have used. Probably here you need to change the coding style than Adding more comments.
Anything else you can think of ?
I found your site on technorati and read a few of your other posts. Keep up the good work. I just added your RSS feed to my Google News Reader. Looking forward to reading more from you down the road!
Where your points are true, it is because of a lack of standards of comments. I have always used comments – that is comments, as is short text, not documentation.
Comments are helpful to identify a significant change to code or a reference to external documentation. They come in handy late at night when debugging code on the Web server, or when trying to figure out changes when source-code control is not available or when not used.
Comments should be written with common sense. I have always used them – going back to my early days as a COBOL programmer now to the Web. Done well, they can be a benefit!
mp/m
Nice points!
But I think you could’ve easily put a positive spin on this post and titled it “5 ways to make inline comments more useful”—it would have done more good.
Inline comments are sometimes essential, not just good. For example, if you code in Perl, lack of inline comments could make the code completely not-maintainable by anyone else (and a lot of times by yourself). Inline comments are also essential if you write “clever” code (clever code isn’t always good, but that’s for a different discussion altogether)—whether you use Perl or not.
In the end it comes down to common sense: if the code is self-explaining, don’t put an unnecessary comment there; but if it is not, be sure to do so.
Nice summary Thej. To me its a trade off. Comments are good, in a way they should only talk about a high level of what ever code its describes. No comments code is like a keyboard without character labels on the keys.
(6) Comments with bad English are worse than any.
(7) Copy comments skeleton from previous method and one may forget to edit. Duuh!
@mike: Completely agree with common sense part when commenting.
@sids: Agree with you when it comes to Perl. For me Perl is write and forget kind of language.
@Vijesh: when you force people to comment then you would see lot many (7) mistakes. So it should be left to the developer.
We got a review comment saying ‘Dont tell me what the code is doing!Just tell me why it is doing!’. This comment was desperately given after seeing this.
// returning the value
return x;
I read a few blog articles under the title ‘Dont comment your code!’ and when i was discussing it with my PM, a simple understanding prevailing was ‘commenting for quality, we cant skip that’.Yes inline comments are for a great help but it should not by any means distract the reader as in the example mentioned above. Naming a local variable status as customerAccountStatus would avoid a single line of comment saying ‘status indicates customer account status’.
hi! your blog is very interesting :)
hi! your blog is very interesting :)
moreover, i am new to this blogging. i like to you to visits my site in your free time ..and give suggestion to improve