[jsmthrowaway]

> 1. When your comments are longer than your code, either you're putting in too many comments, or your code is too hard to read. (The former seems to be the case here.)

I hate this meme. There's nothing wrong with too much commentary. You are not on a comment budget. Please stop spreading this around, like the "rewriting is always a bad idea" meme that's embedded itself in young developers like dogma even though Spolsky's point is up for debate. Atwood is wrong about this one, too, and I hate that Spolsky and Atwood have so many "rules" of programming that people pass around.

I've seen this meme borne out via comment ratio rules in style guides. That's ridiculous. We all work in editors that make comments a different color. I use light gray. My eyes can look right past them, but if I want the paragraph or two explaining the algorithm I'm looking at, it's there. The underlying flaw in Atwood's claim is that it is possible to write code in a way that is self-evident to every reader. You do not know every reader.

Well-written commentary -- bordering on literate programming -- makes development much better. Even better if the code is the documentation. I don't know where this notion that we must conserve comments like water came from, but I'd be happy if it just stopped.

Note here that I'm addressing quantity, not quality. I feel that is important to clarify.

[wfunction]

I think you might've misunderstood what I'm saying. It's perfectly fine to have complex functions commented as much as necessary; heck, it's totally fine to have your comments be 100x as long your function when the function is actually hard to understand.

What's not OK is commenting ALL of your code, especially not to such an extent where the comments are actually longer than the code size on average. (!) Some stuff just has to be self-explanatory, period -- that's a fact, not a meme. If you can't make the simplest code self-explanatory, then I'm sorry but you simply can't code as well as someone who can. And if you're going to comment everything, then you're also wasting valuable time that someone who didn't need to do so would've spent writing actual code and getting more done.

[jsmthrowaway]

I understand what you are saying perfectly, but you typed "you are putting in too many comments" as a possibility, full stop. All of that context you just painted for me is not in your comment. That's how "never rewrite because rewriting is bad because reasons" gets started.

And absolutely I think commenting all your code is okay. I honestly wish literate programming had caught on.

[wfunction]

Well, quantity can be measured in different ways. I didn't say "your (individual) comments are too long"; I said "you have too many comments" (aka the total length of your comments is comparable to the total length of your code... i.e., your source files are on average more comments than code). Too many comments (even short ones) is generally bad; they make the code harder to read, not easier. A few long comments are generally good. I feel like you were addressing a different point than I was making.

[jsmthrowaway]

> Too many comments (even short ones) is generally bad;

That's exactly what I'm refuting, so I'm not sure why you keep talking past me. I am speaking to the crazy notion that there is a par for the comment golf course, and we all have to be Goldilocks as we write software. I don't know where that started, but I'd love it if people stopped judging software based upon the non-executable portions.

A line before every line? Maybe. Are they comments of quality? I've put a comment on every line of assembly before as a postfix. There is no hard and fast rule on this, and I wish people would stop trying to make one.

Again, literate programming. I feel like you're missing how serious I am about this by overlooking my repeated love for it.

[wfunction]

Well in that case, there's nothing crazy about it. If I can hire someone whose code is reasonably self-explanatory vs. someone who puts comments all over their code (whether or not it's self-explanatory), I'm certainly not going to choose the second one over the first one, not sure about you.

[jsmthrowaway]

You just said if I took the same self-explanatory code and added comments to it that you deem unnecessary you'd no-hire me as a result. And yes, that is absolutely crazy, and has been my point throughout this entire thread.

Please do me the respect of researching literate programming before attempting to extend this thread, because I can tell you're unfamiliar, just based on how many ways you're trying to slice and dice a chink in my opinion on this.

[Myrmornis]

Strongly disagree. The fewer comments the better. Reviewing and maintaining code is hard, and within reason you want the code to be expressed in as few bits as possible while maintaining readability and good structure. Comments in English are just another thing for me to have to process mentally when understanding the code. Even worse, there is no constraint on the comments that they have to be accurate. Code at least has to appear to be working correctly. Every single comment added to the code comes with zero guarantee about whether it's true or not. Similarly, the comments can get stale, and there is nothing technically opposing that.

Literate programming is a horrible idea; comments in code encourage verbosity and showing off, lack any guarantee of correctness and should always be a last resort.