Re^4: On comments

[pemungkah]

I have read Programming *is* much more than "just writing code". and it's clear that we come from diametrically opposite points about comments, which is fine. If we were working on the same team we'd need to find a compromise. I'm going to use the rhetorical tool I mentioned a while back in the node about "agressive argument" (Re: What is "aggressive" argument?) to defuse the discussion, which feels a little heated to me: since it is at least partially a matter of taste, this is one of those arguments that can't be definitively "finished" or "won", only abandoned - and I think that this is probably the proper point for me to do that. This is not saying "I'm right" or "you're wrong", just "we're not going to agree about this, I think".

It's possible that I've simply not clearly stated the assumption I'm working from: comments don't actually affect the logic of the program, Smart::Comments aside - but they do affect the logic of the programmer, and what he or she will decide to do.

Intentions, political considerations, external dependencies, and other similar factors that have nothing to do with the local code that's on the page (but everything to do with the context in which it was developed and in which it must run) are important, and that not making sure they are known at the exact point where further decisions need to be made in the source code will increase the chances of those decisions being wrong, perhaps catastrophically so.

I personally think that comments are the best way to do that: right at the code that was affected by the external circumstance (some other obscure code called it, in the case of the debugger, or that variable really does have to be zero or we have a remote root exploit in the Linux kernel source). Is there a better way to communicate that kind of thing at the point of decision: at the place in the code that might be changed without a signpost that doing so would be Bad? Remember, I'm not asking you to make the code clearer; I'm asking you to make the context clearer. What's the best way to do that?

I think we agree that this non-local-code context is important, and difficult to communicate effectively. I would be very interested to hear what ways you use to get all that messy not-code stuff across to "the next victim".

(Edit: spoiler that shows the comments from perl5db.pl wasn't working for me, but is now...go figure. Minor wording changes for clarity.)

[BrowserUk]

There is no "heat" here. This debate will go on--for both of us, and every programmer--long after we've stopped talking. We, just as all those on opposing sides of the debate will simply have to agree to differ.

Remember, I'm not asking you to make the code clearer; I'm asking you to make the context clearer. What's the best way to do that?

That question presupposes that what you've said in the preceding two paragraphs is important to the ongoing maintenance of the code. And that is where we will have to agree to differ.

I don't want to make too much of your example, as your efforts were obviously a labour of love, but IMO there are about 7 or 8 significant comments in there. But, due to (what I consider to be), the morass of unnecessary, irrelevant or downright misleading thoughts, feelings, opinions and speculations--not just duplicating what is clear from the code, but often triplicating or even quadruplicating it once you consider the block comments; inline comments and interleaved POD documentation--it is neigh impossible to pick out those important ones from that morass.

Were I ever to attempt to modify that program--and I might because although I rarely use the debugger, it is useful now and again, but is completely broken in 5.10 on my platform--I would strip all the comments so that I could see the code. I would retain an original and feed any changes I made back into it if I was considering submitting a patch.

But, for me, the very essence of the coders art is the code. And, IMO, trying to read the code when it is so thoroughly concealed in untested & unverified--indeed, untestable & unverifiable--prose, is like trying to study the stars from the middle of a major city. There is just so much extraneous noise that it completely swamps what is actually important.