A thought experiment; what if I changed a few words in your post?

Looking at some code I wrote six months ago I came across the following lines:

if (in_delete_grace_period()) { ... }

adjust_time( $check )
    if last_order_needs_time_adjustment();

determine_status() unless $errors;
[download]

I was able to dive right in to what is going on with the code without reading any comments.

That would be great... assuming that those subroutines were able to to be passed the 20 variables that are in scope... and assuming that they are able to pass back the two or three variables that they modified.

You have given a nice contrived example that would certainly work under some conditions - but not this one ((sarcasm)which you "obviously" could've guessed without seeing the code(/sarcasm)). My example came from working code - a small random sample of tens of thousands of lines that are all broken into commented paragraphs. Some sections do look more like what you said - but not often.

Yes I could break into a subroutine every 10 to 20 lines, but then I have a different problem -- the code is arguably more fragmented and less easy to follow and has to find other ways to pass around variables. Some sections of logic cannot be broken up without severely hampering readability, or without serious code mangling - but they can be broken into paragraphs with comment headings.

Update: made sure that sarcastic comment is taken as such.


my @a=qw(random brilliant braindead); print $a[rand(@a)];

Yes I could break into a subroutine every 10 to 20 lines, but then I have a different problem -- the code is arguably more fragmented and less easy to follow and has to find other ways to pass around variables. Some sections of logic cannot be broken up without severely hampering readability, or without serious code mangling - but they can be broken into paragraphs with comment headings.

Maybe that's not feasible for your application as it is right now, but the best Smalltalk programmers I know write exceedingly short methods all the time, in almost every language they use.

I don't think that's an accident.

[...] assuming that those subroutines were able to to be passed the 20 variables that are in scope...

Any FORTH programmer would immediately jump at your throat for saying this. This is a red flag: if you need to pass around more than 3 variables, you're more than likely doing something wrong, in the realm of factoring. A simple function should never need more than just a few parameters.

There is certainly the case for long methods/subs/procs/funcs if the code is just following one long sequence of actions. A lot of Delphi code that I maintain does that and I think it's not a bad state for that particular type of code, even though the Delphi IDE has auto code hyperlinking, which is great for skipping from one method to another. On the other hand I find that where there is branching it is best to use short methods/subs/procs/funcs that are preferably no more than one screen long, not actually that different from code 'paragraphs'. I general, what most people really want is not strict adherence to coding standards, but to see most of what they need to at a glance and either a short method/sub/proc/func or a code paragraph should be used where applicable.

I think the main thing is the advice above the Perlmonks masthead: think about loose coupling. Looser coupling means less copying and pasting should happen. The less copying and pasting, the less need for parallel maintenance and the less chance for hard to find bugs. The two TDDs should facilitate looser coupling. I learned Top Down Design at school (though it doesn't always come naturally) and I'm now (several years too late) trying to get my head into Test Driven Development. I'm too conservative to be into Xtreme refactoring, especially for maintenance, but I have recently found a bit of refactoring to be useful in my own code.

How can you feel when you're made of steel? I am made of steel. I am the Robot Tourist.
Robot Tourist, by Ten Benson

No programmer can expect to account for all maintenance programmer shortcomings, but that does not free you from the obligation to try.

I'm sorry, but we will probably have to agree to disagree on this. To my mind, that is exactly what it does do.

There is simply no way for me to predict what gaps there will be in the knowledge of any programmer that will see my code. Or what they will find difficult to understand. Or what idioms they will eshew as 'too complex'. I do not know who they will be, or what their experience levels will be. Or how many of them there will be. Or what their personal coding preferences, prejudices or blind spots will be.

Given that uncertainty, the best I could hope to do is include the entire contents of perldoc in a comment at the top of every program. Ridiculous you say, but it isn't. As far as understanding the vagaries, inconsistencies and idioms of Perl is concerned, that is the definitive answer. The idea that I could write it better is ludicrous. That it should be a part of my source files is more so.

No amount of documentation (too much, too little, or just right) will ensure that the maintenance programmer will read your documentation. Use comments and documentation.

What makes you think he would read the comments?

The first thing I do in most every piece of other peoples code I pick up is to throw away the comments (in a copy!). The second is to manually reformat the code to my personal preferences. The third is to 'fix' any obvious verbosities, by recoding them to use (my preferred) idiomatic constructs and discard any extraneous (used once intermediary) variables.

Only once I have been through the entire file, line by line, and any related files required to allow me to form an understanding of what the code actually does--not what the author thought it did--do I even consider going back and looking at the authors comments. It's often very illuminating with respect to the authors level of understanding of what he wrote :) And only after that process is complete do I consider myself even vaguely competent to consider modifying that code. Even then, if this is real code that I am about to modify, I may well feel the need to add a bunch of trace statements and run it before I will consider attempting to modify it. I never, ever take comments to be the truth.

Take those three comments you posted above. From those comments I can derive quite literally zero information about what that code, or the program they were a part of, is designed to do. You might, but then you wrote them. But to me, they are entirely and utterly meaningless in the absence of further information.

However, if you had posted the code, minus the comments, I'll bet that I could derive a whole lot more information than is included in those comments. Often as not, if there is a code bug, or a subtle potential bug there, I'll find it. But if I read your description of what you think you code is doing, before I read the code itself, when I do read the code, I'll probably not question it as closely, and so come away with the assumption that what you described it was doing, is correct.

Code is precise; words are not. Words are ambiguous and open to interpretation; code is not. The meaning of the words you use is subject to your education, your context, your prejudices, your mood, your experiences etc. etc. Your code suffers from none of these flaws. Programmers tend to comment those things that they personally found difficult to code or understand. They reflect their own abilities and knowledge, not that of the people they are (supposedly) writing the comments for. Even when you are your own maintenance programmer, you run the risk of influencing your own thought patterns back into the same (incorrect) groove you were in when your wrote that code.

One of my favorite debugging techniques, (for my own code when time and circumstances permit), is to simply abandon it for a while. Leave it as is and go do something else for a while before coming back to it and trying to understand it again. The intervening period of time doing something else, preferably something very different, has the effect of washing my mind of all the assumptions and conclusions that I had previously reached about a problem and allows me to focus on it afresh. To come at it from a different angle. And so often that allows me to see the assumptions I was making. And see the errors in those assumptions.

If I comment the code with those assumptions, then when I return to that code, I'm likely to fall right back into making the same assumptions, and the same errors.

I'll say it again. Extensive comments are redundant and dangerous. I use occasional and sparse comments when I feel they truly clarify a piece of code, but in general, my choice to not comment my code has nothing to do with being lazy. It is an explicit and conscious decision based upon my personal experiences of the quality of comments I've encountered and the value I perceive they have.

There is simply no way for me to predict what gaps there will be in the knowledge of any programmer that will see my code. Or what they will find difficult to understand. Or what idioms they will eshew as 'too complex'. I do not know who they will be, or what their experience levels will be. Or how many of them there will be. Or what their personal coding preferences, prejudices or blind spots will be.

Well yeah. And there's no way for you to be able to predict whether the folks here on perlmonks can understand these sentences you wrote, and even after trading remarks back and forth on the subject several times, you may still have some doubts about whether we can follow what you're saying here, and difficulties like this arise in every single aspect of communication right on down to choices of appropriate subroutine names... and yet we all must muddle through, as best we can.

You may be someone who can read code better if it has no comments: don't assume everyone is like that.

(Would you like some help writing a comment-stripper script?)

You may be someone who can read code better if it has no comments: don't assume everyone is like that.

The point is, that comments lie; code cannot.

(Would you like some help writing a comment-stripper script?)

No. I have an editor macro that handles that just fine thanks :)

---

Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.

"Science is about questioning the status quo. Questioning authority".

In the absence of evidence, opinion is indistinguishable from prejudice.

"Too many [] have been sedated by an oppressive environment of political correctness and risk aversion."