If the Comments Are Ugly, the Code Is Ugly 660
itwbennett writes "What do your comments say about your code? Do grammatical errors in comments point to even bigger errors in code? That's what Esther Schindler contends in a recent blog post. 'Programming, whether you're doing it as an open source enthusiast or because you're workin' for The Man, is an exercise in attention to detail,' says Schindler. 'Someone who writes software must be a nit-picker, or the code won't work ... Long-winded 'explanations' of the code in the application's comments (that is, the ones that read like excuses) indicate that the developer probably didn't understand what he was doing.'"
Re:The comment may also be complex.. (Score:1, Informative)
complex perhaps, but usually most comments are just plain irrational.
Comment removed (Score:5, Informative)
An addition (Score:3, Informative)
Dennis Ritchie has a whole page of comments [bell-labs.com] in the Unix source code, and what information they convey.
Re:The comment may also be complex.. (Score:3, Informative)
On the basis of your username, I'm perplexed as to why you somehow failed to properly letter the items of your list. Perhaps "c) ???" should have come in front of "d) Profit!" (well, a rather long and windy version of "profit", but boils down to it basically)?
ROFL, because I'm a moron, that's why. Honestly, is that so hard to understand?
Re:Well, duh. (Score:3, Informative)
That is not the fault of the practice of commenting code. That is the fault of lazy-assed developers who don't maintain the comments.
That's like saying engineering is rigorous because the profs insisted on it so it has become a habit. It is rigorous for another reason -- in this case, a lot of experience has shown that overall, commented code is easier to maintain. It is exceedingly rare to see code which is only ever maintained by one person over its lifetime; if you've ever tried to fix a Steaming Heap of Innovative Technology which is utterly un-commented you might see why people insist on it.
I've worked on a lot of different code bases over the years, and most of the originally written by other people. I've seen developers let go because they didn't/wouldn't comment their code (well, that was part of the reason). The manager was a former coder, and expected that if you're working in his code base, you're going to adhere to his rules. Those included commenting code and adhering to standards. Failure to comment meant you were only doing about half of the job.
Not commenting code, and not keeping the comments up to date as the code changes is a very good indicator that the coder in question isn't doing his job as thoroughly as required. If you write software for a living, it really is a weak excuse to say that comments aren't helpful and tend to be out of date over time -- that's pretty much a circular argument since the reason the comments aren't helpful/accurate is because people haven't maintained them.
Cheers
Re:The comment may also be complex.. (Score:3, Informative)
You've obviously never actually built a real world building. You'd be damned surprised at how inexact so many things are. Something may measure 12 feet on the plans, you may take a 12 foot board to place and when you get there, you'll still cut it to fit or hammer it into place. Construction, even of your vaunted bridges is filled with hacks carried out at all levels of the build.
Software development typically isn't engineering. It's usually a business of maximizing productive features versus minimizing cost and time. Rarely is the answer to further investigate working code.
Re:The comment may also be complex.. (Score:3, Informative)
As a programming "old coot", I'd say that if you didn't understand why, then yes, by definition that's bad coding. You need to understand the problem before you can fully address the problem. And if the solution is complex, your comment shouldn't say, "Wow! I can't believe this worked. Good luck if you need to change it!" It should instead educate those that come behind you. Comments should be an aid to understand not only the code but the problem domain addressed by the code. It's a means of recording knowledge that the code doesn't make readily apparent.
Commenting, Like programming is an Art (Score:2, Informative)
Re:The comment may also be complex.. (Score:4, Informative)
Also known as survivorship bias [wikipedia.org].
Re:bad spelling in variables/etc get me (Score:3, Informative)
America isn't the only country in the world. In England and Canada, "honour" is the correct spelling and "honor" is the "alternative" spelling.
--- Mr. DOS
Re:Real Programmers... (Score:1, Informative)
A lot of times, I have comments like that, because I wrote the comments before I wrote the code (i.e. pseudocoding in advance).
Re:You are not expected to understand this (Score:3, Informative)
So here's an example of a comment that does an excellent (I assume) job of explaining why the code is doing what it's doing, yet the whole thing is so complicated that Ritchie even needed to acknowledge that the comment probably wasn't going to be of much help either with an amusing, and now somewhat famous, statement.
Sorry but that is just a piss poor comment and there is no excuse for glorifying it. If it's that complex, he needs to refer back to a particular section of a particular version of a design document. If there is no design document one needs to be written. There are times when what you're doing is so complex that the only sane option is to refer to more extensive documentation rather than try to explain it inline. That is not an excuse for a supposedly witty cryptic comment.
Re:You are not expected to understand this (Score:2, Informative)
The first C compilers/linkers would only look at the first 8 characters of identifiers to determine equality. That kind of limits the sort of names you could use in a OS sized code-base and still maintain uniqueness. I'd say it was better to keep all identifiers under 8 characters than to risk the possibility of unintended ambiguous names.