http://www.perlmonks.org?node_id=614273


in reply to Re: Programming *is* much more than "just writing code".
in thread Programming *is* much more than "just writing code".

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.


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.

Replies are listed 'Best First'.
knowing your audience
by doom (Deacon) on May 09, 2007 at 08:05 UTC

    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.
        No. The point is, that comments CAN lie. But they usually don't.

        By the same token code CAN lie -- either through complexity resulting in misinterpretation, or by function names that don't do what they say (such as a routine named die_with_errors that actually only warns). But code usually doesn't lie.

        BrowserUK:
        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.

        You're a contractor aren't you. You've broken the hippocratic oath of programming - you know - the one that says "First do no harm." At the places I work, which have been with teams of 5 to 20 perl programmers of various abilities and coding styles, that sort of attitude doesn't fly. At the very least it inflicts your choice of programming style on everybody else - even if your choice of programming style is the best. At slightly worse level it removes comments that other programmers may have been using for visual cues - even if you don't use them. Getting worse it kills CVS annotation which is actually a valuable thing to have when tracking changes. And potentially the worst is that you have refactored all of the code that was probably working just fine - now rather than testing just the broken bug, you have to test for all of the other errors that you may have introduced. Good thing you have a test suite, but sometimes you don't.

        Patient: Blurp! (breathe) (wake)
        Doctor: Oh - good morning glad to see you're waking up.
        Doctor: How do you feel?
        Patient: gack!
        Doctor: Well, you're good to go now. We took care of your appendix.
        Doctor: Oh and while we were in we lipo-suctioned your abdomen, removed your gall bladder, performed a bypass, refactored your nose, placed skin grafts over your tattoes, and shrunk your stomach.
        Patient: But it was just my appendix.
        Doctor: Don't worry. I figure you're 30 pounds lighter. Your much more refactored and simple now.
        Patient: But it was just my appendix. (gasp)
        Doctor: Oh - and we removed one of your kidneys.
        Nurse: Doctor - he only had one kidney.
        Patient: (die)


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