Hacker News Reader

Hacker News

Comment by hakunin | Hacker News Reader

Full thread

hakunin

Seems like an appropriate time to share my 4 reasons to leave a code comment:

1. An odd business requirement (share the origin story)

2. It took research (summarize with links)

3. Multiple options were considered (justify decision)

4. Question in a code review (answer in a comment)

View on HN

5. To add sections to code

Code is writing, would you write a technical book without sections and chapters?

If you can't organize your code into sections and chapters using the constructs provided by your programming language, for everyone's sake, get a better programming language. If you're not allowed to, get a better job. If you can't right now, then go ahead and use comments for that purpose, but I pity you.

comments are constructs provided by the language. QED :)

It's a semantic argument, but I'd say they're clearly not language constructs. The format of a comment is completely unspecified by almost any language. In the cases of something like JavaDocs, it may be structured, but it's a very different language than the primary. The only mechanism provided by the language is the 1- or 2- character escape hatch for exiting that language and entering unstructured comment-land. I suppose emergency exits are "provided" by a movie theater, but I wouldn't call them a function of the theater, nor a normal part of the theater's usage (hopefully!).

They’re specified by the english language

You should really use different modules/classes/files and folders/packages/namespaces for this.

I've not been doing 4, but it's s great idea. If someone's asked the question, it's likely it will come up again for the next person reading the code!

As an aside, my first try is always to try to clarify the code itself if someone has a specific question, so the obvious answer is in the code. But if I'm unable to signal that in code, a comment will do just fine.

I couldn't fit this part in my tweet, but this is an important caveat.

These are almost exactly my own reasons, except I have #5 - annotations as needed for some php frameworks, and especially for ide intellisense.

E.g. if the ide can't grok what a $var is you can do :

    /** @var Some\Namespace\To\Class $var */
    $var = ...

then when it reindexes things it has no problem tying everything together.

2. Is very applicable to workarounds often linked to 3rd party issues.

Good list. I would add: 5. todos

Reply on news.ycombinator.com