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

There's a big difference between "what"/"how" and "why" comments. "This increments a variable" is a stupid comment because the code already says it, but a note such as "I'm using this particular data structure/algorithm/etc. because ..., even though ... seems like a better choice" can speak volumes. It's hard to make code itself clearly convey intent (careful naming is the main way), and it's the first thing to get buried by verbose code.

If you have documentation about the design of the system and write reasonably clear code, you can document sparsely. (Having fewer comments also gives those present added emphasis.) As with most engineering, it's more about trade-offs than hard-and-fast rules, though.



Yup , that was my point on the "doc-comments where appropriate". Overall design of the system can/should be expressed with a good,well-written README.txt. I know UML is "supposed" to solve that problem but not for me.




Consider applying for YC's Summer 2026 batch! Applications are open till May 4

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

Search: