Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer

Why I'm a Pod::Nazi

by Bobcat (Scribe)
on Nov 22, 2001 at 04:26 UTC ( #126905=perlmeditation: print w/replies, xml ) Need Help??

I've been programming for well over 15 years and have watched myself move from the "comments are for wimps" mentality to the "document the hell out of everything" track.

When I first started programming, compilers either didn't exist for my computer or were rediculously expensive; BASIC was the only option and comments used up precious RAM. When returning later to a program I'd developed, it was often necessary to do a "brain run" several times to figure out what I was attempting to do. Comments would have helped.

Flash forward a few years and I'm maintaining an application written by another person in the company I'm working for. The application is compiled, but there are still very few comments; the "comments take up RAM" option doesn't hold any water any more but I can go and hunt down the original developer to pump his brain for information on why he did specific things. Comments would have helped him.

I'm now writing large applications in Perl and various other languages and I've made comments part of the design process. Comments help me and the other developers organize our thoughts. POD text in the modules makes it convenient for me to keep documentation in sync with the modules.

But, most importantly, the documentation included in my modules saves me hours of time by not having to stop what I'm doing and answer "How do I use this module again?"

Replies are listed 'Best First'.
(ichimunki) Re: Why I'm a Pod::Nazi
by ichimunki (Priest) on Nov 22, 2001 at 07:16 UTC
    I find that POD is great for documentation for users. That is for documenting interfaces to class/instance methods, basic usage, etc. It lends itself to sitting just outside a sub{} block, at the beginning and at the end of a piece of code.

    But for good comments of the # variety, I really like Steve McConnell's suggestions in "Code Complete". Instead of writing code first you write pseudocode first-- discrete, plain English descriptions of what is to happen in this piece of code, indenting to show sub-blocks and such. Then you prepend # to each line (actually I'd just start with them there). Then you insert actual code in between those comments-- having already "rehearsed" the procedure mentally, writing the code is halfway automatic. Then if you have anything in your code that really isn't readable (but mostly it is because you use sensible variable names, keep your statements simple, etc etc, right?) you make a quick note what that does. Ditto if anything your code in has side-effects that may not be visible just reading that bit of the code. Of course, this sort of precommenting with pseudocode takes some discipline, but I find when I use this technique my code is a lot better.
      Let me add a verbal ++ to the above. I've found (over lots of years of experience), that if you can't express it in pseudo-code you probably don't understand (or don't completely understand) exactly how you're trying to approach the solution. There are lots of times when a lack of being able to express something (completely) in pseudo-code led me to the conclusion that I didn't adequately understand the interfaces I was dealing with and the way I needed to manipulate things.

      The really retentive will then go through after the fact and add in the "why" commentary to supplement the "how" pseudo-code. Or, as a button I own says: "Code as if whoever maintains your code is a violent psychopath who knows where you live."

Re (tilly) 1: Why I'm a Pod::Nazi
by tilly (Archbishop) on Nov 22, 2001 at 09:23 UTC
    As the resident advocate of the position that commenting is not an unabashed good, I feel obliged to respond. The issue of what does and does not need comments is one that I have put a little thought into.

    My all-time favorite insight comments remains Re: The Purpose of Commenting. My personal understanding of what I0 said is the style I described in some detail at Re (tilly) 4 (disagree): Another commenting question,. (That is a semi-unfortunate thread. While I like it for the comment, The public posts were paralleled by a series of private /msgs that were more friendly than the public record. I refer back to it because among other things it captured detailed thoughts about why I coded as I did right after I wrote it. But I regret the one-sidedness of the exchange.) I have been happy with that compromise between comments and code for a while now. Comments serve a purpose that code never can. But what you can communicate by coding well, you definitely should.

    (In fact when I next experiment with my coding style I am likely to try commenting less than I do now.)

Re: Why I'm a Pod::Nazi
by dws (Chancellor) on Nov 22, 2001 at 11:20 UTC
    I've been programming for well over 15 years and have watched myself move from the "comments are for wimps" mentality to the "document the hell out of everything" track.

    There's a middle ground. The path to it starts by considering that comments have the potential to be a maintenance burden. The potential for burden increases with the volume of commentary. It gets to be a major nuisance during maintenance when a 2 line change means having to rework 20 lines of commentary. Human nature being what it is, somebody is going to forget to update a comment, and the world described by the commentary can begin to diverge from the truth of the code. Having two divergent stories is a bigger liability than one truth, the code, with no commentary at all.

    Pod documentation carries an additional risk, if one follows the style of locating the pod either entirely before or entirely after the code it describes. Physical distance between code and its corresponding commentary increases the likelihood that the commentary won't be updated during maintenance.

    The middle ground is to locate commentary close to the code it describes, and to write as little commentary as necessary. If comments are close to the code and there isn't an excess of verbiage, chances are greatly improved that the commentary will survive maintenance.

      There was a thread at Inline POD vs. EOF POD a while ago about the joys of inline versus eof POD. While a lot of people seemed to like inline, my strong sympathies go with the position put forth by tye and Abigail that eof is better for POD.

      In particular I liked Abigail's explanation of why inline is a problem. To it I can only add the point that synchronization of POD and code should be far less of a problem than synchronization of general comments and code. The POD is about the public interface. Public interfaces should not be changed as capriciously as code. If you do change them, you need to track down all of the code that used the old interface and change that as well. Compared to that synchronization, modifying the POD is a small cost.

      Comments that need synchronization with code for me go inline. There your point about distance is relevant. But I strongly prefer having POD at the end of the file.

Re: Why I'm a Pod::Nazi
by brianarn (Chaplain) on Nov 22, 2001 at 08:30 UTC
    I couldn't agree more about commenting and how important it is.

    I have two rules that I follow no matter what I code, unless I'm going for a one-line wonder.
    1. Comments should say why you're doing something, not what you're doing something
    2. You're never coding something for yourself, but for the coder who will be maintaining it in the future.
    These are both incredibly important in my methodology of coding. Unless I'm writing bizarre (or obfuscated) code, I can usually tell what I'm doing with the code. It's not a matter of what I'm doing, but why I'm doing it. Someone mentioned that in a prior response, but they said both what and why, whereas I feel that a "This code does X" comment isn't terribly worthwhile unless there's a reason why you're doing that - and then it's worthy of a comment.

    Also, writing code for those who come after you is very helpful, as it keeps people from bugging you with questions about code you've moved on from. ;) A good example of this would be my current position. I've written code that (hopefully) will never have to be updated or maintained. However, that's just a pipe dream. So, since the people who will be coming after me have no Perl experience (cause my boss insists on hiring people with no PC knowledge but with people skills <rolls eyes>), almost every single line of my code is commented with why I'm using a chunk of code there.

    Comments are one of the best tools a coder has - use them wisely. :)

(shockme) Re: Why I'm a Pod::Nazi
by shockme (Chaplain) on Nov 22, 2001 at 05:26 UTC
    I've recently taken to not only coding what I'm doing but why I'm doing it. Although this makes for far more comments than normal (whatever that means), it has certainly saved me many brain runs (e.g., why did I ++$x rather than $x++ ?). A simple line stating "I'm ++$x here because . . ." has saved me probably hours of scratching my head, kicking myself, and wishing I'd bought more beer.

    If things get any worse, I'll have to ask you to stop helping me.

Re: Why I'm a Pod::Nazi
by d_i_r_t_y (Monk) on Nov 22, 2001 at 06:04 UTC

    me too... document the hell out of methods; try to make the code within the method self-documenting by judicious use of descriptive variable names, and comment whatever isn't obvious.

    guess my complaint about POD and Perl is the lack of a more precise documentation markup/syntax. With POD, one can only really =head and =item and such, but what i think we really need, especially in a weakly typed language like Perl is something more like:

    =public =object =method get_name
    =usage  <string> $name = $this->get_name();
    =args  <none>
    =returns $name
    The current user's name.
    Basic accessor method to get user's name.
    sub get_name {

    ...and then someone (me!) could write a parser which would be able to create beautiful, standardised, perl doco for every module under the sun, rather than the diverse, often terse, sometimes overly verbose, and occasionally obscure doco that exists for modules on CPAN...

    just a wish... (thoughts turn longingly to function prototypes in Perl 6...)


      Absolutely not.

      This is a maintenance disaster waiting to happen. When the functionality of the code changes, either the comments stay in sync through prodigious efforts of discipline (that I, in 18 years of coding, have yet to encounter), or the comments drift away from what the code actually does. Hence the dictum:

      Debug the code, not the comments.

      That is not to say that such information is not useful, quite the contrary. But it should be extracted by programmatic a posteriori source code analysis. Think lint. Relieve yourself of work that you can get a compiler to do for you.

      And then there's the issue that this is eight lines of comments for what is probably one line of Perl...

      g r i n d e r
Re: Why I'm a Pod::Nazi
by FoxtrotUniform (Prior) on Nov 22, 2001 at 23:02 UTC

    I've moved from "comment the hell out of everything" to "write obvious code and document interfaces and data" over the past six months or so (yay code review!). It took me about three years to get from "comments aren't really necessary" to "comment the hell out of everything".

    When I started working at Advanis, I'd document every block, and often every non-trivial line of code. The other programmers who looked over my code objected, saying that instead of writing comments, I should be writing more lucid code. I scorned them: good names are difficult to come by. They warned me that lengthy comments concerning the "what" and the "how" would quickly become obsolete and misleading. I scorned them: I saw myself as a disciplined, meticulous programmer who would never let that happen.

    You've all seen this coming: about a month later, during one of my code reviews (arrogant and obstinate though I was, I wasn't dumb enough to spurn code reviews) with one of my block comments circled in scary red ink. The comment was completely at odds with the code (which I'd changed in a hurry during a rather stressful evening debugging run). And the student was enlightened.

    My current project is a large module (large relative to the other ones that I've written) that I hope will appear on CPAN someday. My current approach to documentation is to describe the interface to each function in POD immediately above the function: this takes care of user and programmer documentation all at once, and involves less repeating of information. (And it seems that I'm finally starting to understand what Pike meant when he said "put the complexity in the data, not the code", so the code's simple enough that it shouldn't need documenting... but that's for a code review or three to determine, I guess.) We'll see how well that works.


Re: Why I'm a Pod::Nazi
by hsmyers (Canon) on Nov 23, 2001 at 10:41 UTC
    I am tempted to say something along the lines of “Yes! another sinner sees the light”, but I won't! As may or may not be clear, I tend to come down in favor of more documentation rather than less documentation— believing as I do that communication is a good thing and that while I may at heart always believe that the source is the ultimate code communication, I also don't see anything wrong with helping things along. I also believe that there are times when comments should be set aside, particularly if I want to concentrate on exactly what is going on in a chunk of code. And if it sounds as if I'm slightly schizoid about this, well then that is probably because I am! It would be a mistake to say that code documentation is a do or don't thing, to say that you should do this much and no more or that you could have any hard and fast rule beyond the most trivial. It is a problem that is usually at least as hard to solve as the writing the code in the first place. There are a host of considerations, who is it for, what does it do, will the author maintain it, and on and on. Ultimately this probably reduces to one of those un-decideable things, emacs versus vi etc. Having waffeled—err qualified all over the place, I would observe the following after 25 years of doing this sort of thing:
    • It is far more often the case that there is not enough documentation.
    • It is usually easier to make 'too much' into less than 'not enough' into more
    Then again, I should probably admit here and now that I have been known to write code to generate documentation and therefore should own up to the outside chance that I am ever so slightly biased—go figure!


Re: Why I'm a Pod::Nazi
by mortis (Pilgrim) on Nov 26, 2001 at 20:39 UTC
    I have to agree with some of the other responses - Perl's POD is a good first step, but it's inadequate for larger projects. I've recently worked on a project that involved C++, and we decided to try Doxygen for our API documentation. I have to say, I am very impressed with it - it can generated interlinked HTML documentation (ala Javadoc), tex output (with the ability to produce a PDF manual), and manpages. It has facilities for documenting at the class level, member level, as well as parameters and return values from methods. It generates class hierarchies.

    It is my opinion that Perl would be well served by adopting a documentation tool/format with a similar level of features. The links really help developers get familliar with the project quickly, the generated hierarchy diargrams and collobration diagrams really aid in understanding object hierarchies.

    There has been some talk about this for Perl6


Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://126905]
Approved by root
[ambrus]: choroba: heh heh... I have such a doc bug report somewhere. fixed by now.
[Corion]: Once upon a time I had automatic tests for checking the synopsis, but I stopped doing that because the setup was too fragile on CPAN testers for extracting code from the SYNOPSIS.
[Corion]: Maybe I should move the extraction of the code from the SYNOPSIS section into the author tests, or something like that...
[choroba]: Corion Sounds reasonable
[Corion]: choroba: Yeah - I basically have the same for regenerating README and README.mkdown already, except that I do that in Makefile.PL, but I guess one or the other thing should somehow work ;)
[ambrus]: was this bug: https://rt.cpan. org/Public/Bug/ Display.html?id= 59814

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (8)
As of 2017-02-27 12:12 GMT
Find Nodes?
    Voting Booth?
    Before electricity was invented, what was the Electric Eel called?

    Results (383 votes). Check out past polls.