Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

Re^5: Stupid mistakes I repeatedly make

by Anonymous Monk
on Mar 28, 2005 at 19:51 UTC ( #442933=note: print w/ replies, xml ) Need Help??


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

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


Comment on Re^5: Stupid mistakes I repeatedly make
Re^6: Stupid mistakes I repeatedly make
by Anonymous Monk on Mar 29, 2005 at 12:03 UTC
    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

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others taking refuge in the Monastery: (11)
As of 2014-07-23 17:18 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (148 votes), past polls