Hacker News Reader

Comment by seanmcdirmid | Hacker News Reader

Comments are like footnotes in a book: great for adding context to the main text, but they work really well when shoved off to the side somewhere, easily accessible to those who want them, easily ignored by those just into the main text (e.g. Author). Unfortunately, code typography is so horrible in our field that we lack the ability to use the bottom page margin or a side bar for this purpose, so we hack it up with what's easy: syntax highlighting.

View on HN

Comments also lie.

At best, they are a statement that, at the time they were last edited, the author believed their stated facts were true, or might become so, plenty are aspirational, "this is what this function or change to it, which I've not yet written, will do".

He might have been wrong, or the code might have changed without updating the comment, the actual running code is the only truth.

To some degree I agree, but even if they don't lie they can still get in the way of code reading given the current sad state of code typography. If comments were handled better, I bet they would be updated more regularly with code changes since it would be more of an eye sore if they weren't.

I find that comments at the top of functions are helpful when implementing an algorithm found in reference material, especially if they have a citation. At least that way you can check that the function appears to do what the reference material specifies.

But generally commit messages, descriptive symbols, simple logic, short functions, and unit tests are better.

Reply on news.ycombinator.com