Comment by king_magic | Hacker News Reader

Comment by king_magic | Hacker News Reader

Well, I'm not going to completely dismiss him as a "cranky old dinosaur", but I don't agree with him, and frankly, I find it insulting that he issues a blanket declaration that those with 5-10 years experienced are "crazy teenagers", especially after showing pretty poorly written representative "good" code of his own.

If I, a developer with 6 years experience, am a "crazy teenager", then he reminds me of a "senile old man". He has a few valid points, but overall, I think his message is unhelpful.

I've written the occasional verbose comment before. Why? Well, for context: I was on a 20 person team, working on a poorly designed 750 KLOC codebase for a medical X-ray application. His example of incrementing a counter could have meant the difference between needing to re-shoot (and re-radiate a patient). When we made changes to critical pieces of the code (which were poorly designed before we ever touched it), we had to be exceedingly clear as to why.

While my personal commenting style is more along the lines of his second code example, I see actual code in that function as pretty awful. It's long. It's confusing. The execution path through that code is not immediately clear. Sure, it's dense, but not in a good way.

So, the while the author is free to rant, I think he should take a deep, hard look in the mirror before throwing out blanket criticisms of other developers the way he does.

English-language comments are usually full of prepositions, ambiguous terms and mostly stuff that was meaningful just to the author. Words about data in our out, upstream or downstream are always useless because nobody else has any idea what point of view you're taking (data produced BY your code, or produced FOR your code?)

If you think you're making things clear to somebody coming after you, I'd guess you're wrong most of the time.

And then, the code changes but the comment doesn't. Now its downright misleading.

Also it's arrogant to imagine somebody who writes good code can also write good prose. Testing shows most folks are good at one or the other, right? Math or English, few can do both.

Unless they are an idiot savant, anyone who can do math very well can learn to use English (or whatever their native language is) competently. Anyone who says otherwise is making excuses, usually for laziness.

Here's an example from our colleagues at Google (WebRTC):

        //how many frames should have been received since the last

        // update if too many have been dropped or there have been

        // big delays won't allow this reduction may no longer need

        // the send_ts_diff here

        num_pkts_expected = (int)(((float)(arr_ts -

                                           bwest_str->last_update_ts) * 1000.0f /(float) FS) /

                                  (float)frame_length);

Once meant something to somebody. Now its gibberish. Even the variable mentioned is no longer in the code.

"And then, the code changes but the comment doesn't. Now its downright misleading."

Sorry, that's just a failure of the programmer, same as any other coding mistake they may make. It is by no means a reason to not have comments.

Disagree! Disagree!

Having essentially the same code written in two places (code and comment) absolutely BEGS for them to get out of sync. Its why we write modules, subroutines etc - get it right once.

Comments are evil if they mention the code. They should be about constraints, the compiler, your wife, ANYTHING but the code.

I didn't say the comment had to be describing the code in terms of what it was doing, but it absolutely should describe why something was done. If that "why" changes, then the comments should be updated.

This isn't double documentation -- it's complementary documentation. Code is the what, comments are the why. If one does not match the other, then again, that's on the programmer.

Reply on news.ycombinator.com