Hacker News Reader

Comment by bottlepalm | Hacker News Reader

If you can't understand why the code is done in a certain way from reading it then the code is missing comments or needs to be refactored.

Even code you write yourself, given enough time, you will forget the why unless you wrote comments. In a way comments are as much for you as they are for others.

Even before AI, understanding code you didn't write is essential to working on a team of other developers. If you can't understand the code from reading it, then that's part of the feedback loop - too complex, needs comments, etc..

On large teams you'll spend as much time reading code as you do writing it. And long term when it comes to writing maintainable code - the ability for others to read and understand it, including the why of it, is paramount. Your code could literally be around for decades.

View on HN

> If you can't understand why the code is done in a certain way from reading it then the code is missing comments or needs to be refactored.

Code is never missing contexts. If what your code is doing is not obvious to the reader, it is bad code that needs to be fixed. Things like cryptic low-level expressions should be extracted to helper functions with descriptive names or even extracted into a class, and classes need to comply with the single responsibility principle.

yeah that's how a simple algorithm that would fit on a napkin gets broken up into a soup of ravioli that I have no hope to understand. I often end up refactoring it into a simple function in a branch so I can figure out wtf is going on.

> yeah that's how a simple algorithm that would fit on a napkin gets broken up into a soup of ravioli that I have no hope to understand.

No, not really. You get spaghetti code by being unable to refactor your code to follow inconsistent level of detail across calls. That's the textbook definition.

Once you start to follow basic code quality and software engineering principles, you'll notice right away that your code becomes both easier to understand and to test.

My code is fine, thanks. It's other people's code that I have a problem reading.

Ah the classic thinking that 'code documents itself'. It does not. Some devs are so full of themselves they think their code is so good that it is obvious what their intent was. It never is obvious, and just ends up as tech debt. Write comments.

> Ah the classic thinking that 'code documents itself'. It does not.

This is demonstratably false. Case in point: all the code that does not require comments for developers to understand what it does.

> Some devs are so full of themselves they think their code is so good that it is obvious what their intent was. It never is obvious, and just ends up as tech debt.

That's why you need to address the problem in the PR stage and aggressively refactor code that fails to be clear.

This is not rocket science.

> Write comments.

No, that's just compounding the problem. Now you attached comment noise to cryptic code, which means not only do you still need to decipher the hot mess of a code you cannot parse on your own but you also have to parse the comment next to it to try to understand both.

And God forbid they get out of sync.

The solution is already known for over a decade: write clear and obvious code. Extract weird expressions into helper functions.

Codex barely writes any comments, while Claude makes a slop article for every one line commit. I’d enjoy something in the middle.

Try antigravity. I think it generally has the right level of comments.

Yes exactly. I don't like Codex not writing comments - and even proactively removing useful comments! There was some change in the last month that causes Claude to write crazy long comments. I routinely have to ask Claude to 'tighten' up the comments before the final commit.

Reply on news.ycombinator.com