Why programmers don't want to comment code
Why don't developer comment their code?
This is a question I will try to answer by summarizing my life experience.
I've been coding most in PHP but I coded also in a few other languages but the majority of code I have written is PHP so I am a PHP programmer and that has shown me a lot of ugly thoughts why people just wont comment their code.
So here are some of the reasons why most of my colleagues and team mates didn't wont to comment their code and often find more appropriate to delete mines too so they see more REAL CODE than bullshits like comments and lines that separate CODE from DESIGN and so on.
"I'm lazy!"
Well I am lazy too. Laziness is the reason why people are so advanced these days ;). That is why I personally comment my code. I don't want to figure it all out again later cause I forgot what it was and how it works. Think about it. If it is commented you will never have to figure it out again because you have written down an explanation of all the weird parts. It ease everyones work if you haven't got to figure out the problem again every time it comes up.
"Good code is self-documenting!"
The programmer that thinks that way thinks his code is so good that any moron could understand it without comments. After all good code is self-documenting is it? Totally wrong! There are many pieces of code which just could be understand by looking at it. For example because they are one line of code. But in the big picture most of the hard to code algorithms aren't obvious at first look to all the programmers even to you if you look at it after a while. So hard, complex algorithms and code blocks should be documented.
"Upper management doesn't care about comments!"
The BOSS looks at the metrics supplied to him. These usually are like lines of code, hours spent at work, tasks completed or simply does this work. But just cause time spent commenting is not reported or your boss isn't interested in it doesn't mean it isn't important at least to you. The better your comment skill is, the more productive you will code when you rewrite or upgrade your code later. This will decrease some of your hours in the long term so putting some extra time in the beginning might be a good idea.
"I'll never work on this after I'm done!"
This is the normal newbie mistake. So when you have finished your first project and all went well with it you are ready to move on the next one and you do. You might get a couple of more projects done but then they start coming back to you. It is not because they were bad written but because the users wants new features. The idea is that if you have written something once you will most of the time (99% of the time) need at least a piece of it again.
Well I think I gave you enough reasons to think about this for a moment and at least give it a try. After all how bad could it be to put an extra sentence at the end or at the top of your code block ?
Well have fun with your comments...
and your well written never reused code too ;)
I will really appreciate comments on this topic.
And if you have in mind another reason why programmers just wont comment their code feel free to share it with us ;)
15 comments:
i don't comment or comment on a very high level coz it is a pain to keep the comment in sync with the code. (ie. code update => updating comment too).
worse than 'no comments' wud b 'outdated comments'.
Yes, good code is it's own documentation. Because I don't document, I take extra care of choosing the right function/variable names, or even rewrite less readable code.
Documentation obfuscates code, it describes what the author thinks the code will do, and not that what really happens at runtime.
Only exceptions for documentation:
- Some explanation in front of a function, or on top of a module, on how to use the code.
- When code is intended to look like a bug, like an exploit, bug workaround or some undocumented language feature.
Documentation does describe what the author thinks the code will do, but more importantly, it describes what he or she wants it to do. This makes it easier to spot where someone made a mistake.
When setting out to create a class or method, I personally find it useful to comment for everything I intend to do. I then write the code around the comments. Often I just delete them, but in other cases, it serves me well to leave some there.
Comments are especially useful when working in a framework you had no part in planning or creating. "Why did they use this when they could have used that?" You don't know unless there's a comment there. It doesn't mean the comment is necessarily correct, but at least it gives you a sense of what the author had in mind.
It's hard to set one rule about commenting that applies to all situations. I generally try to write self-documenting code, but I put comments in where I think it would help the reader. Anything that might be perceived by a reader as astonishing or unintuitive I will decorate with a comment. Of course I try desperately to avoid writing clever or unintuitive code, because if the code is as clear as the comment would be, then I don't really need the comment, do I?
Generally I'll put comments above classes to describe the responsibility of the class, because this helps me think about the single responsibility principle. If I'm using the word "and" a lot in the description of the responsibility, perhaps I should have more than one abstraction.
Like Kirubakaran said...
Comments on how code works gets out of sync with the code.
Here is the best way imho:
Put header blocks around functions/classes/methods to explain use, input/output.
All "comments" then go into the code repository systems on commit/updates.
And when I say comments I don't mean explaining what the code does (that is clear from reading the code).
Comments should explain the INTENT of the code, the reason behind it.
Thus looking at a file's log history one can easily figure out what was the logic behind each change and how to modify or tweak it for the next requirement.
tribui
"Self documenting code" is a trap. Some people think that they make the code "self documenting" by omitting comments (which becomes true by doing so) - faulty logic, but mostly caused by a distorted perception what is clear for the original programmer and what is clear for all programmers.
Comments are mandatory in two situations: To document an interface (javadoc, etc.) and to document intrinsic behavior that makes the code work. Intrisic behavior is the exploit of side effect are any specific domain knowledge that went into the code.
A rule of thumb: If the comment is longer than the code, it is either redundant or the code needs rework, trying to be too clever is not smart. Also excessivly long comments might hint that the programmer didn't understand the problem and thus described what the code should do and he didn't manage to implement properly.
Code-reviews are a good occasion to validate comments, so if there is management so there are code-reviews, thus management cares (inadvertly perhaps)
I do a lot of code reviews, and from my experience elegant code is self documenting - and I always try to refactor the code to make it self-explaining. there are a lot of good tricks to do it: short and focused functions/methods/classes with logical names, using variables in a smaller, focused scope, again naming them to reflect their intention. so the code itself is not a problem if it is written with that in mind.
I found that introspection and "intelligent code helpers" in java and c# actually caused people to stop reading comments and documentation in the last few years - they just type in the dot and expect to guess the correct method from the list which IDE offers.
So, as much as I'm in favor of writing good comments annd API documentation, if the method and parameter names are not self-documenting, there will be a lot of problems. Look at Swing in Java - the threading model is clearly documented in code, on the Net, explained in many books, but one of the biggest complaints about it has it's roots in the misuse of the thread model.
In short, documentation is good, but if the code is not self-explaining, and if it's easier to misuse the API then to use it correctly, programmers did not do their job.
In an attempt to dispel the "I don't need to comment my code since if the code is written clearly enough it should describe itself" theory, I present the following:
Definition 1.1
The purpose of code comments is to present intent.
Definition 1.2
A software defect is a deviation from intent. This definition does not make a distinction between implicit (i.e. expected but not defined in a requirement) and explicit (i.e. defined in a requirement) intent.
Theorem 1.1
Code is incapable of sufficiently presenting desired intent.
Proof I will provide an indirect proof of Theorem 1.1 by assuming "code is capable of sufficiently presenting desired intent" and obtaining a contradition. Choose a section of code that contains defects. By Definition 1.2 this section of code does not correctly describe the intent. QED
Notice that Theorem 1.1 contains the word desired. This is necessary to distinguish between the intent that a section of code with defects presents and the intent that is required. Also notice that Theorem 1.1 contains the word sufficiently. Later entries will expound on this in more depth but for now it will suffice to say that code utilizing crafty programming may obfuscate intent.
I do acknowledge that for those who use the "I don't need to comment my code since if the code is written clearly enough it should describe itself" to mean "I'm too cool / talented / whatever to comment" or to cover for "I'm too lazy to comment" that my argument will have fallen on deaf ears.
I have written extensively about comments in my blog at http://www.realityinteractive.com/rgrzywinski/. Just search for "comment".
"A true Klingon warrior never comment the source"
Only seems to be a joke...
Documentation is like sex:
When it's good - it's out of this world...
When it's bad, it's better than nothing...
As a few people have mentioned, comments get out of sync. Clear, well-written tests (preferable written via TDD) make better documentation, because they are forced to stay in sync with the code. As a side benefit, testable code is generally also well-factored and readable.
You still need comments for one situation: to describe WHY your code does something. If your comments are describing WHAT your code does, you probably have room to extract a well-named method or make a similar enhancement to the readability of your code.
It's a good idea to comment our code especially for crowded functions, even with only several words. Better do it, than to sorry when you're trying to read your last year's code.
Good informative article...
Thanks for the writeup.
Hi, well be sensible, well-all described
We are one of the Leading Web Design Company in chennai,our services are web design,website design,web hosting,seo ,sem services,email marketing,mobile application developers in chennai,please add my website into your blogger,it is very useful for us.
Post a Comment