4 ms·
Completely agreed. Put another way: the sentiment that code documents itself is only possible in purely logical systems with no edge cases or surprising consequ
by scott_s 9y ago
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 https://news.ycombinator.com/item?id=9048947
- dhimes 9y agoIt'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.
- vanderZwan 9y ago> 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