Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

In something like your example, the what is obvious. But I've seen a lot of code where the what is not at all obvious, and a comment succinctly summing or breaking it down up would help drive the understanding.

The way is useful in addition to that, and often IME far more important than the what. IMO you should document both, as necessary, and that's the hard part/skill. You have to treat it like you won't remember it in 6 months, because in 6 months, you won't. A lot of devs don't do that.

(A fair number of devs won't follow the style guide / idiomatic patterns of a language if there isn't a CI check forcing them to, and will argue to all ends with a human as to why it ought not apply to them, to the great detriment of their code's readability to other experience practitioners of the language. Oddly CI enforcement usually works better, why I don't know.)



> I've seen a lot of code where the what is not at all obvious

So then the question that needs answering is:

"why" is the what not obvious?

Document the "why."




Consider applying for YC's Fall 2025 batch! Applications are open till Aug 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: