Hacker News new | ask | show | jobs
by antonpug 3119 days ago
Could you be a little bit more constructive? It's okay if you disagree - but I'd be curious to hear your side.
3 comments

I like your article and the example you used, code clarity is vital. Poor code is often accompanied by many poor comments which only helps in overwhelming the next poor soul who has to read the code.

However, I think that the larger the project, the more sense it makes to comment heavily. Again, code clarity needs to be a priority, but so does comment clarity, so much time is spent reading code by humans who are optimized to parse natural language. So we should cater to our users, not just the users of our executable, but the users of our source too!

Some commenting is okay and necessary. The point is that generally, if you are adding heavy commenting, you can probably refactor the code in such a way that commenting is not necessary. Even in a large codebase.
I agree that heavy commenting can be a code smell
I could ... but I'd rather not comment too much :D
More seriously: yes, you should name functions/variables/etc. reasonably. And often if you write a comment, you will find you are actually explaining away a wart. But often you need to document business logic, code that needs to be written in a less than clear way for performance reasons, explanations of why you chose approach A instead of what would seem like another perfectly reasonable approach B, URL links for standard doc PDFs, and a million other little things.

There are comments that aren't necessary if you write your code better, but there's others that are needed even if you write your code perfectly.

Documenting business logic works much better via Spec files - if you have BDD test files Given/When/Then format, that'll go a long way in describing functionality, in my opinion.
Whats the biggest code base you've worked with?