When a comment above a function says “returns -1 on error” and the code does the exact oposite (returns -1 anyway except if there was out of memory error, which may be #defined to -1 anyway) it’s a bit annoying when you first look at it.
Remember kids, comments in code are evil. They are wrong – or misleading at best. They only ever say what one person at some point in the past thought they beleived the code did. The definitive record is the code itself.
(there are possible exceptions to this rule… maybe… internals can be good to document – but arguably it should be *away* from the code so that you don’t start thinking the documentation is accurate and up to date – because it’s not).
This is evil.
I understand what you are saying, but I believe comments can be very useful. I comment my code to remind myself what I was trying to accomplish with a particular task and not necessarily what it will accomplish in all particular cases.
If someone else examines my comments I believe it gives them a starting point for evaluating the code and checking the results. It may give them something to look for.
When I find myself wanting to comment something I look for a way to make the intention of the code more clear. I might extract a few lines into a new method with a name that identifies the concept. Or I might rename a variable. with a more clear name. To remind myself what I am trying todo I write a constraining specification test.
I write self documenting code.
so the maintainer can see what im doing without a comment.
he need only read the code.
meaning if the design changes so radically, yes I will rename a few variables. but not too many as the code is not all written in one function.
what your saying is true.
I like the statement at the end too.
to keep the doc away from the code.
As far as “The definitive record is the code itself” is concerned, I kinda like the following quote:
“If the code and the comments disagree, both are probably wrong”
No, no… you have it all wrong. Comments are not there to tell you what the code does. If you’re reading comments to try to decide what the code does, then you’re reading them wrong.
Comments are there to tell you what the code’s authors and mainters thought it did. Any discrepancy between what the comments say and what the code actually does are potential problems and should be investigated, then either the code or the comments fixed.
Removing comments because they’re inaccurate is like deleting unit tests that fail… it displays a lack of understanding of what the thing is for….
What you have done here is simplified the concept of Design By Contract. Unfortunately, there are a few flaws in your claim. It is not comments that are evil; it is failure to fully specify the requirements (contractual requirements) of an interface.
To use your example, “returns -1 on error”.
Instead, specify the requirement using a test framework (e.g. JTiger http://www.jtiger.org/):
// assert that the system is in a state such that an “error” will occur.
assertEqual(-1, theInterface(), “Failed contractual requirement to return -1 on error”);
This way you have a more complete specification of requirements (absolute can only be achieved with 100% system state coverage), as well as a regression. You simply validate your requirement against the implementation; usually this is automatic in a build script.
Hm, I think you’re right. I’m gonna write a script that removes all comments from my source code. They’re wrong because you said so. Have you written any books and if so, can I have their ISBNs?
Provided you have a well unit-tested code, the comments can actually be really wrong or misleading. Unit tests are never out of sync with the code, while comments are almost always. The code itself is not a good replacement for documentation, but unit tests are. The more tests you have, the less documentation you need.
Pingback: Why comments are evil… | satukubik
Pingback: You Arent Gonna Need It – Code Reuse — Numiko Labs