4 ms·
This "too many comments" argument comes up every time, and I say it's a straw man argument. Apart from new programmers who put those comments in to remind them
by pbowyer 5y ago
This "too many comments" argument comes up every time, and I say it's a straw man argument.
Apart from new programmers who put those comments in to remind themselves what each line does, I haven't seen "comment-noise" since... 2005 sounds right.
If it was common I'd be able to go on GitHub and have my searches spoiled by comments. But instead on GitHub it's the opposite, as it is in my working life: people have gone to a "we don't write comments" default position.
Getting a balance is necessary, but I'd rather we had programmers over-commenting than under-commenting, especially for open source projects where "read the code" is used to mean "we don't need documentation as our code's so great".
It also depends who is going to read the code. Other experienced programmers need different comments than when my code is going to be read by developers who are unfamiliar with the codebase and didn't expect to ever touch it.
I agree with what you say but I encourage people to add comments and then remove them later if not needed, rather than omit them entirely.
- emodendroket 5y agoI don’t. I worked on a program with hundreds of instances of the comment “do this here.” Why not just preface every line with that?
- Supermancho 5y ago> Why not just preface every line with that? Because that's noise that makes reading the code more difficult. Creating a separate markup file that provides comments (even overlapping) that are associated to files and lines, for display in an IDE window seems like the logical way to go from the current style of inlining comments into code.
- emodendroket 5y agoI have my doubts. It seems like that would be even more likely to drift than inline comments.
- Supermancho 5y ago> It seems like that would be even more likely to drift than inline comments. I'm not sure why that matters to utility. If you don't check the documentation/comments and code in a changeset, you are going to get drift. This is regardless of the documentation methodology. How poorly developers maintain code is a constant in the case of drift (lack of rigor), so the method is irrelevant, except in how descriptive it can be. A complex application is a nested logical structure tied to orthogonal business requirements. This is why READMEs and docs folders exist, alongside large block comments, hidden amongst the code. How to best describe code is definitely not to inline it, as that's too limiting for what is to be described.