Slashdot Mirror
If the Comments Are Ugly, the Code Is Ugly
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.'"
complex perhaps, but usually most comments are just plain irrational.
Comment removed based on user account deletion
Dennis Ritchie has a whole page of comments in the Unix source code, and what information they convey.
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?
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
Lost at C:>. Found at C.
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.
t
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.
*** *** You're just jealous 'cause the voices talk to me... ***
Commenting well in a program can be the difference between hours of backtracking, reverse engineering, and other wastes of time. Even if the original programmer is the only one who will ever see them, good comments are just as important as good code. I don't know about you guys, but I find myself having to go back to something I did months and even years ago. Comments make the total difference between a quick add-on/fix or hours of hair pulling frustration. Learn to Code, then learn to comment. That combo is unstoppable
Also known as survivorship bias.
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
A lot of times, I have comments like that, because I wrote the comments before I wrote the code (i.e. pseudocoding in advance).
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.
These posts express my own personal views, not those of my employer
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.