Beefy Boxes and Bandwidth Generously Provided by pair Networks
XP is just a number

Re: Re: Ways of commenting subroutines

by willdooUK (Beadle)
on Mar 29, 2001 at 17:47 UTC ( #68094=note: print w/replies, xml ) Need Help??

in reply to Re: Ways of commenting subroutines
in thread Ways of commenting subroutines

I think that even more than other programmers, Perl people have to take most care to write clear code.

Perl code, with heavy use of RegEx, default variables, and syntax trickery, can be an absolute pig to read (all you one-line-coders, take note!). Code readability has to be one of the most important aspects of professional programming.

And it's all very well making a commitment to comment all your code, but the more comments you add, the harder it becomes to maintiain your code. Either you spend too much time adjusting comments when the code changes, or you don't update them at all: (excuse the Java example)
public String getCustomerSSN() { // return the customer's SSN< return customerSSN; }
public String getCustomerID { // return the customer's SSN return customerID; } the comment (which was already not really necessary) becomes incorrect, making the code less clear.

A good example of code that can be relieved of comments:
if (ftpResponse.charAt(0) == '2') // ftp result in 200s = success
if a method is added to do this test:
public boolean wasSuccessful(String ftpResponse) { return ftpResponse.charAt(0) == '2'; }
...then the original code becomes:
if (wasSuccessful(ftpResonse)) the comment is no longer necessary.

(The above examples come from 'Essential Java Style' by Jeff Langr (Prentice Hall PTR) - a very good book that goes through a series of Best Practise rules-of-thumb. In this case, he goes on to say that one of the few places where comments are necessary is when a method has a dependency, i.e. it requires that another method be executed first.)

I know from personal experience that excessive comments can ruin productivity - on one of my first commercial projects, the head programmer insisted that everyone had a ratio of about 2:1 comments to code (that's two lines of comments per line of code!). The design sucked, so despite all these comments the coding was difficult, unclear and underproductive.

On the other hand, when I worked on a project six months later, using the Extreme Programming methodology (XP), where you are supposed to have practically no commenting, we were writing excellent safe code. One of the idealogies of XP was that code always should be as simple and clear as possible. If it could not be easily understood, it was basically wrong.

I don't want to sound like a Software Engineering lecturer, but I certainly want to say that (IMHO) if a problem is unclear, you really, REALLY should not jump in and start coding it. An extra hour spend dealing with the more abstract design will save you 10 hours in coding, maintainance and debugging, and a good design will make any problem more clear...

(waving goodbye whilst dismounting my high horse)...

Replies are listed 'Best First'.
Re: Re: Re: Ways of commenting subroutines
by Shadowfax (Sexton) on Mar 29, 2001 at 20:57 UTC
    first off, let me say that i do not disagree with you.
    that said, i would like to clarify. i was not refering
    to a problem unclear in that i did not understand. i was
    describing the fact that sometimes the logic needed for
    solving a problem is not obvious, is not intuitive, and
    quit often is not any clearer than mississippi mud. these
    are the times when after you understand the problem, you
    can step back and see the issue still resides in a fog
    bank, but rather than spend all day looking for a nice
    little way to code so that your little sister in elementary
    school can understand it, you bang in a quick and dirty
    line that solves the problem and a nice descriptive
    comment to enlighten your posterity.
    in response to the 2:1 ratio... that's called 2 weeks notice
    in my book. insanity is not my cup of tea, and that is
    clinical right there. if you have not come across a problem
    that requires ugly logic, you have not experimented much.
    i also fall heavily in support of the "hacker ethic" described
    so well by steven levy in "hackers - heroes of the
    computer revolution" in that any code you can write,
    i will write in less lines. (not a challenge, just
    philosophy) "bumming" out instructions
    is the foundation of computer programming and continues
    to drive me as a programmer. if i write something, i
    will write it later in less lines. i do not ask you to
    agree, but i ask you to not insinuate my "more functionality
    with less keystrokes" method is wrong. i do not argue
    that you are wrong because you like to write in cute
    little snippets with no comments, so please extend me
    the same curtesy. thanx, and my what a beautiful horse
    that was.


    "A computer is almost human - except that it does not blame its mistakes on another computer."
      Shorter code is nearly always clearer code, true.

      What I'm saying though, is I always code with readability as my main priority (after making it work, of course) - but then I very rarely have to do any low-level, speed intensive code.

      As for the 'two weeks notice' - that's pretty much how it happened :)

      I won't insinuate then. I will say it.

      It is my belief that while trying to remove lines is a fun game, anyone who thinks that it is the goal of someone who would be a good programmer is missing the point. Being able to write tight code is a result, not a goal.

      The foundation of computer programming is the question, "How do I get this thing to be doing whatever I want?" That means getting it to work now. Having it work tomorrow for 2 things, neither quite what you started with and both harder tasks.

      Now you claim that coming across problems that require ugly logic is a mark of a hacker. I disagree. I think that a far better mark is finding nicer ways to think about problems than the obvious (bad) approaches...

        once again i am assulted by those who cannot or willnot
        agree to disagree. i do not argue your choice of style is
        wrong, i recognize it is merely different than mine. since
        you do not agree that writing the most efficient code by
        removing all unneeded processor instructions is a useful
        practice i will not ask you for help in beginning work
        on a new o/s. that's fine, it should not cause me to say
        you are missing the point of being a good programmer. i
        also never said it was the point, merely the method i
        use to accomplish my goal of becoming the best coder
        in the world. we all gotta have dreams don't we? i did
        not say coming across problem that require ugly logic is
        the mark of a hacker, i said not being afraid to use the
        down and dirty answer, which is often NOT the obvious way,
        is the mark of a hacker.

        -everlasting gobstopper

        "A computer is almost human - except that it does not blame its mistakes on another computer."
      I suppose considering your later posts that this a waste of time, but i felt the urge to make the following comment about something you said:

      "hackers - heroes of the computer revolution" in that any code you can write, i will write in less lines. (not a challenge, just philosophy) "bumming" out instructions is the foundation of computer programming and continues to drive me as a programmer.

      I have read Steven Levys book too, several times actually, it was inspiration for me in my younger years and I gave it to all of my colleagues as a Christmas present last year. From reading it I know that bumming instructions was a pastime performed by programmers using unbelievably small memory spaces (probably less ram than is in a digital wrist watch these days) on CPU's with minimal instruction sets at the very dawn of the computer era. (Consider that Knuths MIX is supposed to be representative of computer from two or three generations after the TX0 and code bumming, and it _only_ has 4000 words of ram.)

      but i ask you to not insinuate my "more functionality with less keystrokes" method is wrong.

      Yes thats _exactly_ what im saying. Bumming ops has nothing to do with the modern era where we have virtually unlimited ram (in comparison anyway) and rarely (if ever) write in assembly. (Embedded systems may be the exception, but my guess is that you arent doing that)It has even less to do with the use of languages like perl. In perl there are many many things that can be reduced into a minimal form, great for the programmer, horrible for efficiency. A simple example is the following:

      my ($x,$y)=(1,2); #one line, SLOW ($x,$y)=($y,$x); #three lines. fast. my $tmp=$x; $x=$y; $y=$tmp;
      On this level I recall Knuths explaination for why all of his code is presented in MIX, not some high level language (I paraphrase, when I get home ill get the proper quote and add it to the bottom of this post)

      Programmers are inclined by lazyness to write code as efficiently as possible, for them. This means that in a high level language they tend to use the constructs and mechanisms of the language in a way that reduces the required keystrokes. Unfortunately these construct rarely produce optimal code.

      There are lots of posts about optimisation, I've even been burned by the subject a couple of times (an example is here and Tilly provided me with an excellent link on the subject: Code Tuning you will note that I was set straight in a variety of ways) but I assure you that in most languages, and especially perl the smallest program is almost definately _not_ the most efficient. Which means that your 'bumming' game is a plain and simple waste of time, and not only that it'll probably produce sub optimal results. Note that the computer pioneers (Greenblat and co) probably didnt care about this as their primary aim was to get the maximum amount of functionality out of the smallest memory space.

      Oh, regarding your pecular formatting, I read one of your other posts where you say you defy convention as a matter of course. Thats cool. Lots of people do it. In fact odds are many of the people here by virtue of being hackers do as well. But they also understand that there are times, such as communicating with each other, when conventions are not foolish social constructions but rather the result of years and years of figuring out how to do something as efficiently and as error free as possible. Your habit of all lower case with no paragraph structure is difficult to read and therefore unlikely to be taken seriously. Assuming you are from an english speaking nation, I wonder if in your urge to defy convention you communicate only in pig latin? Or perhaps in Navaho?

      You are not ready to use symrefs unless you already know why they are bad. -- tadmc (CLPM)

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://68094]
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (7)
As of 2018-06-20 07:35 GMT
Find Nodes?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?

    Results (116 votes). Check out past polls.