in reply to Ways of commenting subroutines


i use a modified version of the microsoft flowerboxes
used in Visual BASIC standards. i include the name of
the finction in the top line and it's kinda obvious what
else i do.
i chose this method since the whole thing is easy to read,
easy to modify, and contains all the info you could really
ask for as a person walking into my code. it is usually
more detailed than this, but in the interest of space:
#***<StringToArray>*************************************************
# Purpose: Combine 2 strings into 1 array
#
# Inputs : 2 strings
#
# Outputs: 1 array
#
# Programmer         Date        Comments
# ---------------    --------    --------
# Bob Smith          03/30/01    Created
#******************************************************

[download]
as for the comment to write clear code and not
complex/hard to understand/ blah blah blah:
i do not believe that clear or obvious code is
always the best answer to the problem. sometimes
a difficult to see or downright ugly answer is the
perfect trick. if you only write clear code, then
good luck with unclear problems.

sincerely Shadowfax

"A computer is almost human - except that it does not blame its mistakes on another computer."

Edited Wed Oct 17 23:37:54 2001 - Footpad

Replies are listed 'Best First'.
Re: Re: Ways of commenting subroutines
by willdooUK (Beadle) on Mar 29, 2001 at 17:47 UTC
    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;
}

    [download]
    becomes: 
    public String getCustomerID
{
    // return the customer's SSN
    return customerID;
}

    [download]
    ...so 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

    [download]
    if a method is added to do this test:
    public boolean wasSuccessful(String ftpResponse)
{
    return ftpResponse.charAt(0) == '2';
}

    [download]
    ...then the original code becomes:
    if (wasSuccessful(ftpResonse))

    [download]
    ...so 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)...
[reply]
[d/l]
[select]
      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.

      Shadowfax

      "A computer is almost human - except that it does not blame its mistakes on another computer."
[reply]
        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 :)

        willdooUK
        --------------
[reply]
        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...

[reply]
        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;

        [download]
        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?

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

[reply]
[d/l]

In Section Seekers of Perl Wisdom