Beefy Boxes and Bandwidth Generously Provided by pair Networks
Think about Loose Coupling
 
PerlMonks  

Re: Maintainable code is the best code

by hsmyers (Canon)
on Oct 03, 2001 at 07:16 UTC ( #116341=note: print w/replies, xml ) Need Help??


in reply to Maintainable code is the best code

First thing, if you're going to whip up a maxim, it should be The best code is maintainable. Better when you start out with a truism. Can't say as to how anything you've said is arguable—all good rules of thumb to follow, with one small quibble. You said:
“Minimal commenting explaining what variable names do not”
Would suggest you change Minimal to something a good deal stronger, say like Sufficient for instance. Small change, world of difference. If you make the change then it follows that the person who decides what sufficient, is the maintainer, not the programmer (skipping the obvious case.)

hsm

Replies are listed 'Best First'.
Re (tilly) 2: Maintainable code is the best code
by tilly (Archbishop) on Oct 04, 2001 at 19:42 UTC
    I strongly suggest not changing that word. The connotation with minimal is that you are avoiding having too much in the way of comments, and I think for working code directed at working programmers, that is correct.

    Follow the thread at Re (tilly) 2 (disagree): Another commenting question, for explanation of why it is important to be minimal. (As I always point out, behind the scenes we were trading /msgs that are unfortunately not public record, and were much friendlier.) Read that and get back to me on whether you think that minimal is the wrong word...

      My comment stands. Are you sure you understand what I said? Perhaps given the tone of the discussion you pointed towards you did not. I am sure that I need not point out what the word Sufficient means— if you percieved it to mean “every line” or some other such nonsense let me re-assure you that, that would be wrong. What I meant is precisely what I said—I said change the emphasis, I didn't say change the amount. If a program needs no comments then so be it, if not then adjust accordingly. As I have pointed out before, one of my techniques in taking over projects is to create a copy of the source without comments, since initially I prefer to see what was written, not what someone thought was written or something that was true once apon a time or any of the other problems that documentation is prone to.

      hsm

        I believe I understood what was said, but I may not have understood it like you wanted me to.

        My point is this. Saying "minimal" indicates that one should not view verbose commenting as a way to turn bad code into maintainable code. Saying "sufficient" bears no such implication. Cutting loose with volumious comments is sufficient but not minimal.

        Hopefully we find ourselves in agreement on what kind of code is best for maintainability. However one we are in agreement on that, then the question is what kind of statements will lead people to that end. My contention is that it is better if you say minimal. First that statement already makes it clear that there are are things which cannot reasonably said with clear variable naming. Second it makes it clearer that comments do not substitute for what can be said through good naming. And finally it makes the point that while further things need to be said, it is is a maintainability issue to say them at too much length.

        Saying sufficient communicates more strongly that there are things that cannot be said through good naming which need to be said through comments. But it does not stress that commenting can be overdone, and does not indicate to what extent comments don't replace naming.

        Now which message is more important to get across clearly depends on what your audience is. However it is my belief that the message indicated by "minimal" is more likely to be applicable to the random PerlMonk than the message indicated by "sufficient". Perhaps a better phrase is something like, With minimal comments that are sufficient to the cause...

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://116341]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others perusing the Monastery: (5)
As of 2020-10-30 11:11 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My favourite web site is:












    Results (278 votes). Check out past polls.

    Notices?