Commenting code
Dec 6, 2008 Technology
Commenting code has always been a debatable topic, especially if you have people like me in the team who tend to ignore commenting unless and until they think that they themselves may need this comment. But I have seen code files having a comment at almost once every 10 or 5 lines, I m not sure if it is of any practical use other than making the code completely unreadable. I firmly believe in the concept of English text explaining the logic of commenting, but you don’t need to do this to a developer. A developer should be able to understand code in any possible format and not rely in comments, because coding becomes one of the ways of communication for the developer, he has been with it and has to able to talk and understand code.
Never comment code; if it is hard to write, it should be hard to understand as well.
I am not someone who says a complete no to comments, but i have some point of views like these
- if there is a simple routeA way of doing something and a complex routeB way of doing something, and if your code has routeB, there should be comments to say why not routeA. this may not be right example, but for me comments can be used to explain why a a particular piece of code behaves like this
- The code itself can be used to make explanations, or the code can be made readable so that comments become unnecessary (e.g)
// method to run database query
public function oprDB_q() { };
can be replaced by
public function runDBQuery() { };
- well ever famous FIXME’s and TODO’s
- .. well if i find some more reasons, i will put them up.
December 20th, 2008 at 6:21 am
Few days ago, someone spoke to me about having the following comment format on code. The person was just suggesting. This means no harm to his innocence, just that it was too funny for me..
Read this,
In every piece code, above each edit
// [DATE:TIME] {why not timezone?} | [Person Edited] | [Reason for edit] | [Other Effects]I wish i could have said “then why on earth do we need subversion and issue tracking, we could might as well junk the system with 2 million lines of code(1.8 million of them being comments) ha ha.. ”
The problem of commenting code is inherent to the system, its that when a developer comments the code , they tend to feel that his or her part is done; they tend to ignore he best practices in naming conventions and instead use comments as work around for it.
Programs should be like classical poems, not like maths answer sheets with scribblings and corrections everywhere, that is why you call them a programming language…