Coding Without Comments
codinghorror.com
codinghorror.com
//XXX I don't know why this works
...
//XXX Worst kludge of my life
...
//FIXME this whole pile of crap needs re-written // Here there be magic. See datasheet for details; they explain it
// almost as well as I just did.
/* bad code */
To this day I do not know if this was a comment on the quality of the code that came after it, or if the developer was reprimanding the code.
In those times when you have to do it the Fast and Ugly (tm) way, it's nice to make a comment that you really don't like the code. It adds some humor, and lets the maintainer know that there is no emotional attachment to that section of code.
Of course, this is the first thing that everybody says. And since everybody says it, everybody thinks it must be true. But my experience has been that if you really want to do good work, it turns out not to be true (say) 80% of the time. So the next time you find yourself making a mess because you believe you "have to", you could try stopping and questioning that assumption. You might surprise yourself. How do you think I learned this? Certainly not by following what the majority of programmers believe.
Edit: Rather than using phrases like "the Right Way", I'd suggest toning things down and looking for a way. There are many ways. If you get in the habit of thinking there's only one, and it's capitalized and trademarked, the bar seems a lot higher than it really is.
Every once in awhile we're stuck at 3 days to code freeze (the product isn't a website, so we physically send out a DVD with our product on it, so quietly pushing out hotfixes isn't an option) and come across a bug that almost no user will care about that has two solutions:
1) Fix the problem the correct way. We don't know exactly what the correct way is, but we know it'll take a month or longer to code.
2) Apply some hack that gets it to work. This is usually something ugly and imperfect, but it's possible to do in 2 hours. We can tackle the problem again and attempt to get at a better solution.
If we don't ship on time, we lose piles of money. Guess which one we end up choosing ;)
Option 2 is fairly rarely chosen, but all it takes is for it to happen once or twice to have comments like the above in code, and forgotten.
Right... that whole Right Way (tm) thing is mostly tongue in cheek. It almost always refers to the way I want it done, and is a fairly flexible way.
I've made my living writing code for the last 12 years. How likely do you really think that is?
There's a deep streak of passivity among a lot of programmers. That's part of why they (we) tend to be downtrodden. The belief that one must do shoddy work unless "given the go-ahead" to do good work is as much a part of the problem as anything else.
While I'm sure it'd be nice to know all of the answers all the time, some of us mere mortals can continue to try to notify other people that extra attention should be paid to the code following those comments.
Sometimes doing it The Right Way would necessitate a big refactoring of the supporting code or learning a concept in more depth and I can't afford all that overhead (which might break flow also).
Also, sometimes a far-reaching refactoring might be carried out in stages over a number of hours or days and to go from where you are to The Right Thing you'll have to pass through a number of less-than-optimal stages. But I always find it easier and faster to use an incremental approach where I accept suboptimal solutions, most of which will be quickly overwritten anyway than trying to do The Right Thing all at once.
Sometimes I think I should make a macro out of //HACK:
I can't tell you how many automatically generated documentation trees I've seen that are utterly worthless. Documentation of public interfaces gets mixed in with usage notes on internal structures, and you don't know what you're supposed to use.
I routinely start with comments that psuedo code my idea and then add the sections of the code.
If I can't remember how everything is supposed to work while I'm writing it, what hope does the intern 2 years from now have in adding a new feature?
I've noticed that my Javascript is usually very readable and doesn't require commenting for the most part. I think using MooTools has a lot to do with it, those libraries all encourage good naming practices.
But there are many places in the code, where it is highly desirable to explain by plain words, why certain solution was adopted, that certain part is a bug fix, or why some part of the code is counter-intuitive. I for one am much more happier when my colleagues comment their code extensively.
To look at it from the opposite side: Is there any inherent problem with having too much comments? (provided they are correct).
Also, another problem with too many comments: this is more stuff to maintain. Chances are, the programmer already has enough to do!
You can decide one way or the other whether to compile them as no-ops in releases, but it seems like a big improvement either way.
I try to datestamp my comments, but I've seen some of the above with dates three years old. Why?
Once you make a point of never doing this, the psychological pressure has to find another outlet, such as just fixing the code in the first place.
The trick is to highlight comments with bright & contrast fg/bg color combo that hurts your eyes (it also serves to say 'hi i'm comment, i'm important, but delete me when u understand me')
This is true because code is designed partly for computers while comments can be written entirely for humans.
This is important because comments only have to be written once and maintained occasionally while code without comments has to be reinterpreted every time it is read.
eg: code like this in ruby can explain itself very well!
display_error if not valid_input
Now I do understand that comments cannot be replaced entirely and sometimes it is necessary to add notes to understand the code thus I prefer using comments sparingly and avoid long headers on top of each file. Those headers with author name, dates and other information is unnecessary if right tools are used to maintain your project.
display_error unless valid_input
It's a big world out here, there's room for Spock and for Kirk.
OTOH, you made a much more interesting statement than simply saying you didn't like "unless," you took things into a discussion about programming languages resembling vs. not resembling English.
Ruby has a bunch of lispy things that have nothing to do with English, but it also has a bunch of Perl-inspired things that have a lot to do with expressing logical ideas in English-y "prose."
If you can reconcile those two things, then yeah, you'll like all of Ruby. If not, you'll probably find a subset that pleases you. So sure, I can see that you might like the Ruby you use.
My point was that I think an explicit not is clearer than unless in cases sufficiently complex as to require stopping to think about it. If you're trying to keep track of multiple negations, then having one be in a different form than all the rest does not help. (And meanwhile, there is nothing wrong with a habit of always using if).
In total, yes, but that does not mean that there are no things that work in English that also happen to work in code.
Furthermore, it is difficult to generalize about this: some programming languages are entirely unlike English and work very well, others attempt to be like English and are terrible, while others attempt to be like English in some ways and work.
And further to that, some parts of some programs attempt to be like English and work well, while other parts of programs work well when nothing like English.
Now while I understand bang, andand, and oror, they are a terrible legacy of our C++ days. Bang is especially unforgiveable. If we must have a prefix operator, what is wrong with ~, the actual standard symbol for negation?
;-)
p.s. This thread may seem to be a digression, but it seems quite pertinent to an article that talks about writing code for readability.
Hunh, that hadn't occurred to me! That's a really interesting conjecture, touching on design trade-offs in neat ways. Thanks!
display_error if invalid_inputAlso I think in general hackers should learn to read code. To reverse engineer. To understand what is going on without comments. Then when you do have some comments, it's a bonus (Or just even more confusing and contradictory).
There are differing degrees to which this is true. Different languages had different design motivations. Smalltalk was specifically designed to be readable by humans. By grade school aged humans, actually! In the Smalltalk community, most regard comments as a "Code Smell."