logoalt Hacker News

bob1029today at 3:03 PM1 replyview on HN

I've seen "clean" codebases that conform to "best practices" which are even less decipherable than what you describe.

100KLoC sounds like paradise compared to the latest codebase I touched. Having the signal to noise ratio fluctuate wildly at every member & file is highly distracting. When the information is dense and consistent, you can drop into a flow state more easily.

Four character variable names might sound awful but they can have an advantage. It's a form of compression once you are adapted to it. It forces you to keep things simple. When we can write an entire novel for a variable name, we may be tempted to inflate the scope of a solution.

No comments is universally a feature. If I want justification for a section of code, I am going to check git blame, PRs, linked issues, email, project management system, etc. The only code comments I value less than those written by humans are those written by LLMs. It is beyond pointless to shit up a codebase with this stuff. You could just ask the LLM to give you a live interpretation of the current state of the code instead of risking something falling out of sync.


Replies

ChrisMarshallNYtoday at 5:31 PM

Eh. I've found a "happy medium." I generally restrict comments to headerdocs at the function and property level. I use descriptive names, and keep the functions relatively small and task-oriented, so they do a fairly decent job of documenting themselves.

Every now and then, I'll insert a "why" comment, if I feel it's necessary.

I wrote about my technique (and reasons), here: https://littlegreenviper.com/leaving-a-legacy/