Hacker News Reader

Comment by jerry40 | Hacker News Reader

Why do they remove comments? Do they delete commented code or textual comments?

Your standard docblocks, even if the docblock explains what the function does if it's not clear. You'll basically have a function with zero comments. It's painful, I've never been given a reason as to why.

Why can’t you just read the function itself?

Maybe the real problem is people writing code that is so hard to understand you need a comment to explain what it does.

- Even if some code doesn't need a comment to explain what it does, you may need a comment to understand why it does it, or why it does it in this particular way (which seems non-obvious but is the result of the obvious approach having previously failed).

- Some algorithms are inherently complex and difficult to understand, so they may actually need comments to explain how they work.

- If code deals with entities in the real world, like bank accounts or car engines, it may be subject to rules that are not obvious just from reading the code. Comments can explain the relationship between the code and the domain the code is operating in.

On my past job I was dealing with something like this and in my opinion source files aren't the best choice for a place to contain such information. To me having a quick reference to an internal documentation is the best: it's just a one line on the screen and when you need to update the information you have a centralized place to do so. If you have programmers that actually give a damn said programmers can learn ins and outs of the domain more easily this way, not to mention that this knowledge can serve non-programmers as well (for example help your support team in solving the issue without engaging the developers of giving your manager visibility into the internals of your work).

I'll hazard a guess that it's because it's quicker to delete than update them.

Reply on news.ycombinator.com