Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
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; }
becomes:
public String getCustomerID { // return the customer's SSN return customerID; }
...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
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))
...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)...

In reply to Re: Re: Ways of commenting subroutines by willdooUK
in thread Ways of commenting subroutines by stephen

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others imbibing at the Monastery: (5)
    As of 2014-09-20 04:25 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (152 votes), past polls