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

Completely agreed. Put another way: the sentiment that code documents itself is only possible in purely logical systems with no edge cases or surprising consequences.

As an example, our code base has a comment which refers to our internal issue tracker which itself refers to this HN comment: https://news.ycombinator.com/item?id=9048947



It's also only possible if the code is thought of as a text and is proofread/edited rigorously for reading. My process is 1) write the code quickly- add comments 2) revise for clarity and efficiency (usually modularity), remove comments as confidence allows. This is where I might get the variable and method names correct for self-documenting code. Usually it takes several passes. But most often, "good enough is good enough" and I leave comments in. Just in case.


> which itself refers to this HN comment

I was secretly hoping you actually meant your own comment, creating a recursive loop. But a surprise John Nagle is even better




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

Search: