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

I think there are levels:

Level 1: Garbage code with no or bad comment.

Level 2: Garbage code with good comments.

Level 3: Good code with comments

Level 4: Code good enough that it doesn't need comments, with rare exceptions.

Each level is better than the previous. You can't level up directly from 1 to 4.

Still, 4 is the best level. I know it sounds weird if you haven't seen it.




I don't think level 4 exists. There is no code for problems of sufficient complexity that are self-explanatory. There are too many hidden assumptions and foreknowledge and tradeoffs and decisions baked into a block of code that, unless it's trivial, there's no way code itself can reflect it adequately.


I have three things to say about that:

1. I did allow for "rare exceptions". Some things do need to be explained outside of the code. Maybe we're not so different after all :)

2. There are a number of techniques to write such code. Before I learned them, I had NO IDEA. One is to take what would have been comments and use them as variable or function names. This includes (and I had real resistance before I accepted this) breaking out a variable of function only in order to give it an informative name. "Level 4" doesn't just happen. You work at it for a long time and sharpen your skills in that area.

3. To me, much of the art of writing software is to find ways to divide a complex problem into simple pieces. If my code is real complex, I look for simpler way to write it. And I look hard.


It does exist, but only for snippets, sections of code, or at best whole individual functions, especially in languages that are concise and expressive (which are most languages that are not Java ;-). But even really good code still needs comments about how things fit together, what to find where, etc., because those things are generally not expressible in programming languages, although a good module system can help a lot with that.


I still think a file should have at least some small comment at the top to help orient the reader and set expectations.




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: