Hacker News Reader

Comment by CuriouslyC | Hacker News Reader

Comments rot, and details about what is going on is better incorporated using good variable names and functions that abstract aspects of a task from their implementation.

While I don't like comments that try to explain what code is doing (write better code), comments are very useful for annotating WHY code does what it does. They're also very useful for adding documentation references, code use gotchas and things that need to be addressed in the future.

View on HN

Comments are critical for explaining the code that isn’t there. False starts, obvious optimizations that don’t actually work, etc.

I've heard these sentiments very frequently from junior programmers, and almost never from senior programmers.

I'm guessing most of the senior programmers you've interacted with are maintaining established software with low churn and high availability requirements.

I hear comment love very frequently from enterprise engineers working with 10+ year old Java codebases, but very infrequently from hackers working with young code bases in more concise languages (complex algorithms aside).

Complete opposite for me.

I think it's better to document the context/intention/business reasons and let the code speak for itself.

This assumes everybody reading the code at the company have the skill to read it.

Where I work, I can expect my scalacode to be read by people who can barely write a line of it, and I routinely read typescript and go code while being totally inept at those.

I bless comments that are here to help the reader read, and I let those behind too where there's some specialists-only syntax.

Reply on news.ycombinator.com