Hacker News Reader

Comment by hrabago | Hacker News Reader

This is why we put comments there. Personally, I put comments so future me will remember what the heck I was thinking when I wrote it.

That said, there's no doubt there's code that definitely sucks. Some of it is mine, too. If I wrote it last year, it sucks. If I wrote it yesterday, it's really great. You can really see how much I've learned in a year when you compare it with my previous sample. At least if I have to rewrite the old code, I'll know what traps and special scenarios I need to watch for if I properly commented it.

View on HN

I believe it's a good thing when I see code I wrote 6 months ago and think it sucks. If I thought it was perfect then that would be a sign that I hadn't learned much since I wrote it.

A better question might whether you think the code you wrote 6 months ago sucks as much as the code you wrote a year ago

This could be a good metric to see if you are actually improving or if you are jumping the gun on labeling code sucky.

A lot of people think code sucks if they simply can't understand it at a glance. Of course you think yesterday's code is awesome, you just worked on it yesterday. But in 6 months, with the issue completely out of your mind, even if you haven't advanced, you might think it sucks.

> I put comments so future me will remember what the heck I was thinking when I wrote it.

People who don't do this: please don't underestimate the importance of this.

Be descriptive as possible with the comments on possibly clever/incomplete code - you will thank yourself months later when you realise:

    x += 1 # border

makes no sense to you.

Yes, at the time you wrote the code, it's perfectly obvious to you, but you will forget it and think to yourself next time: 'wtf is this being incremented by 1 for, what about the border, is the border being incremented?'

If you hesitate even for a second about the possibility of your code being misinterpreted in the future, either fix it on the spot or add a damn descriptive comment.

You can drown code in comments, though. In your example, saying "x += borderW" would be as expressive, and tie that context to everywhere else it was relevant. Some comment issues are really better handled as (variable/function/method/structural) naming issues.

Comments are better for explaining the rationale behind seemingly arbitrary or crazy design decisions - "I would have done obvious thing X, but that causes huge problem Y". Why, rather than what. For things that provide important context, but could not be expressed in the language itself.

Many "what" comments should instead be static typing declarations, asserts, or tests. At least that way, people will notice when they no longer hold. Comments are just declarations the language ignores. (Citations, like "implements algorithm X, see Okasaki 1999", are fine though.)

The border example was a bad one, I meant what you said.

Reply on news.ycombinator.com