Beefy Boxes and Bandwidth Generously Provided by pair Networks Frank
There's more than one way to do things
 
PerlMonks  

Re: IYHO, what do you consider good code?

by logan (Curate)
on Jun 13, 2003 at 04:31 UTC ( #265579=note: print w/ replies, xml ) Need Help??


in reply to IYHO, what do you consider good code?

I have a unique problem as a coder. I have a lousy memory. Terrible. For some reason, I can remember the names of singles by obscure punk rock bands, but the proper placement of the comma in an open statement refuses to settle into my brain.

Frequently, I have to revisit code I wrote a year or more ago, and figure out what it does and why it isn't doing it anymore. Ergo, I'm comment guy. Each subroutine I write has a profile at the top something like this:

#--- # sub get_build_from_server # Takes: server_name, password, path_to_build # Returns: 0 for pass, 1 for fail # Called by: main # Calls: &parse_build_name #---

The essential concept is to insure that I won't have to spend a lot of time figuring out what a sub does. If I do something "clever", I put in comments explaining why. A few times, I've gone so far as to include the chapter in The Camel Book/Perl Cookbook where the concept was discussed. Also, if the main chunk of code is a loop, it helps to list the exit condition at the top.

You might also find the Perl Programming guidelines/rules thread instructive.

-Logan
"What do I want? I'm an American. I want more."


Comment on Re: IYHO, what do you consider good code?
Select or Download Code
Re: Re: IYHO, what do you consider good code?
by helgi (Hermit) on Jun 13, 2003 at 11:02 UTC
    Yes, but with proper naming conventions, most of this comment is redundant.

    If your subroutine were something like this:

    sub get_build_from_server { my ($server_name,$password,$path_to_build) = @_; # do stuff here my $success = parse_build_name($path_to_build); if ($success) {return 0;} else { return 1; } }

    --
    Regards,
    Helgi Briem
    helgi DOT briem AT decode DOT is
      Sure, for a simple sub like the one I used as an example. But that's like saying we wouldn't need a big table of contents if only people wouldn't write long books or if people wrote clearly we wouldn't need synopsis or abstracts. Sure, it probably isn't necessary to have a 6 line header for a 6 line sub, but if the sub runs to 20-30 lines, I'd rather have the header.

      The idea is that I'm trying to make it easy to follow program flow. Two years later I want to be able to look at it and instantly see what it does and how it should be called.

      -Logan
      "What do I want? I'm an American. I want more."

        if the sub runs to 20-30 lines, I'd rather have the header

        Obviously if it works for you...

        However, if it were me and the sub ran to 20-30 lines that I couldn't understand without half a dozen lines of comments I'd refactor it into a larger number of smaller subs - each of which I could understand without half a dozen lines of comments.

        I doing code maintenance I tend to ignore comments, since I find that they're out-of-sync with the code half of the time.

Re: Re: IYHO, what do you consider good code?
by DrHyde (Prior) on Jun 13, 2003 at 11:13 UTC
    A couple of years ago I wrote a little script to tell me what called what and so on. It grew and mutated and is a crufty mess (not good for code which is meant to help with making other code more maintainable!) but you might want to take a look. It's on my website. Patches welcome, especially any which make it play nicely with the guts of perltidy. I've spoken at some length with the author about using his code, but lack of tuits has meant I've done nothing about it.
Re: Re: IYHO, what do you consider good code?
by dopey (Sexton) on Jun 13, 2003 at 15:16 UTC
    If everyone used these kind of comments it would make the world a better place. I can't think of how many times I tried to reuse a sub that someone else wrote, and had to "dig deep" into the code to figure out what arguments the sub used.

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others musing on the Monastery: (12)
As of 2014-04-24 12:47 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    April first is:







    Results (565 votes), past polls