Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

Re^4: Stupid mistakes I repeatedly make

by merlyn (Sage)
on Mar 28, 2005 at 17:52 UTC ( [id://442878]=note: print w/replies, xml ) Need Help??


in reply to Re^3: Stupid mistakes I repeatedly make
in thread Stupid mistakes I repeatedly make

I deliberately use shift now, more and more, for two reasons:
  • I have a personal coding convention that all methods should begin with "my $self = shift" (or "my $class = shift" for class methods).
  • It opens up a place for me to comment on the expected type:
    sub map_names { my $mapping = shift; # hashref of first-last names my $insensitive = shift; # boolean: should uppercase be the same? my @names = @_; # remaining parameters are names ... }
    With the "my ($x, $y, $z) = @_" style, I don't have a clean place for those comments, unless I want to break the list on the left across many lines (ick).

-- Randal L. Schwartz, Perl hacker
Be sure to read my standard disclaimer if this is a reply.

Replies are listed 'Best First'.
Re^5: Stupid mistakes I repeatedly make
by Anonymous Monk on Mar 28, 2005 at 19:51 UTC
    With the "my ($x, $y, $z) = @_" style, I don't have a clean place for those comments, unless I want to break the list on the left across many lines (ick).

    Why not just put the type documentation into the embeded programmer documentation above your function? To call your function correctly, others need to know what they can and can't pass to it, and what will happen if they do. In other words, the type information is a valuable part of your function interface documentation.

    I embed the documentation for my function interfaces (as well as general 'programmer' documentation), within a special pod section, dedicated to the "programmerdocs" pod translator. When I need to extract the user documentation, the regular pod translator ignores the programmerdocs section. When I need to extract the programmer documentation, I have a twenty line perl script that extracts the 'programmmerdocs' section, and pipes the results of those sections to the standard pod translator.

    It's a bit of an abuse of the pod translator concept, but it works, and it keeps the two kinds of embeded documentation separatate, and easy to access. If anyone has a better method for keeping distict forms of documentation separate, I'm open to suggestions. So far, abusing pod has worked for me.

    I like extractable function documenation, because it allows a tester to write unit tests for all the functions without reading any of the implementation details. If the code doesn't match the documentation, the coder needs to fix one or both of his code or documentation.
    --
    Ytrew

      Why not just put the type documentation into the embeded programmer documentation above your function?
      That creates a distance between the action and the documentation. That's harder to read for the maintainance programmer (the further away, the more movement in the editor needs to be done). It also makes easier for the documentation and the code to get out of sync.
      To call your function correctly, others need to know what they can and can't pass to it, and what will happen if they do.
      But the comments merlyn was making weren't intended for the user (then they would be in the POD) - they were there for the (maintainance) programmer. Two very different beings. With different needs. And different documentation.

      When I need to extract the programmer documentation, I have a twenty line perl script that extracts the 'programmmerdocs' section, and pipes the results of those sections to the standard pod translator.
      I hope I never ever have to maintain your code. Comments should be right there where the code is, and not somewhere tucked away where I need a different tool to read them.
        That creates a distance between the action and the documentation. That's harder to read for the maintainance programmer (the further away, the more movement in the editor needs to be done).

        So, you'ld take a single line cryptic comment, scribbled as an afterthought by the original coder, over a well documented formal interface specification, written directly above the function declaration, and visible to the maintainer in question? Nice.

        But the comments merlyn was making weren't intended for the user (then they would be in the POD) - they were there for the (maintainance) programmer. Two very different beings. With different needs. And different documentation.

        *sigh* That's why my usage of POD allows for two classes of documenation, due to the two different intended audiences.

        I note that you carefully excluded the most important audience in your little diatribe. What about the testers: you know, the ones who's job it is to verify the code against the comments, and bitch if they find any flaws? When the interface is well documented, the code can't fall out of spec with the interface documentation, because it's a flaw in the code or the interface if it does. The testers can verify this without reading a single line of code; this helps keep them independant of the coder, and the codebase.

        I hope I never ever have to maintain your code.

        The feeling is more than mutual. You've stridently and vehemently opposed a form of literate programming that allows for clearly documented interfaces, eases the burden of unit testing, and provides a formal mechanism to ensure that the code matches the comments, none of which you provide cogent alternatives for.

        If I want documenation on a function, in my code, I just run a script, and read the docs. I can even auto-extract the call tree for my program, and generate a hierarchical set of documentation by function for every function in my program, and how it should be called, and why. I can choose to just display function purpose overviews, drill down into the calling requirements, or even link back to the matching section of code to check the implementation details.

        I can give it to someone else to sanity check flow and the logic, or show it to the maintenance programmer so he can get a comfortable view of the what of the program, without getting bogged down in the how

        By constrast, you've just got a big mass of implementation details, with a few unverifed comments scribbled in by the coders when they have the time. To decipher how your code works, I need to search for the appropriate function, and start guessing about whether your comments are correct or not, double-check the test suite to determine whether or not it's up to date with your latest comments, see if the comments seem to match the code, reverse-engineer the proper specification documentation (that you oh-so-proudly didn't write), deliver it to the testing department, and keep it all up to date manually. Or just give up on it all, because it's "too much work" when you have to start verifying everything from scratch each time.

        Comments should be right there where the code is, and not somewhere tucked away where I need a different tool to read them.

        Yes, a difficult tool -- called a scrollbar. I can see how that would be hard, especially considering the terrible information you might be exposed to. Oh, no! You might be able to view the entire purpose of the function in a unified context, all it's required inputs, required output, intended use, and error handling specifications, as opposed to the joyous challenge of deciphering the unstated intent of some ugly mass of code. Horrors!

        --
        Ytrew

Re^5: Stupid mistakes I repeatedly make
by Mutant (Priest) on Mar 29, 2005 at 11:19 UTC
    It also lets you do:
    sub foo { my $param = shift || croak 'Param must be supplied'; }

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others having an uproarious good time at the Monastery: (5)
As of 2024-03-19 09:45 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found