http://www.perlmonks.org?node_id=916127


in reply to Documentation: POD vs Comments

POD is documentation for the *user* of your code. That could be an end-user, or it could be a programmer who is using your code. POD should document what the code does.

Comments are documentation for the *maintainer* of your code. Comments should document how the code does what it does. So for example it documents the algorithm and anything else that might not be immediately clear to a maintainer.

So, for example, in this module the POD simply tells you what methods exist, what arguments they accept, and what they return, and then there are comments like:

# we override these in the test suite to avoid having to be root ... sub stat { return CORE::stat(@_); }
but that subroutine isn't even mentioned in the POD. It's not something that a user needs to care about.

Then in the subroutine that does the bulk of the work there are small comments every few lines that explain all the steps in the algorithm:

# if a user has been specified, first get their UID (from their # username if necessary). ... # now divine the user's permissions. first get the file's mode # bits and ownership ... # now check user/group perms. Set isReadable etc if the mode has # the owner bit set and the user is the owner, or has the group bit # set and the user is in the right group ... # root can read and write anything, can execute anything # with any x bit set

As an aside, I'd note that comments are really only useful in conjunction with the user-level documentation. Maintainers needs to know both what the code is supposed to do and how it does it. Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents. Scattering POD inline with code is Good, putting it all at the beginning or end of the file, separate from what it's documenting, is Bad.

Replies are listed 'Best First'.
Re^2: Documentation: POD vs Comments
by JavaFan (Canon) on Jul 22, 2011 at 14:19 UTC
    Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents.
    That's quite subjective. If *I* were the maintainer, you wouldn't score any brownie points.

    But, as you said, POD isn't there for the maintainer - it's there for the user. POD doesn't have any way of modifying the order in which it appears in the source file. While there are some cases where you may present the documentation in the same order as the corresponding code appears in the source file, IMO, more often than not, that's not in the benefit of the user. My POD often contains sections that aren't directly related to any specific code (usually, only parts of the DESCRIPTION describe code), and those that do, I usually want to present them to the user in a different order. I may want to describe often used or general functions/methods before less often used, or specialist functions/methods. And sometimes I want to describe my methods in alphabetical order.

    Interleaving POD with code means that the flow of your manual page depends on how the code was written. This is a case of "implementation shining through". Which I think is a thing that should be avoided.

Re^2: Documentation: POD vs Comments (proximity is not clarity)
by tye (Sage) on Jul 22, 2011 at 18:31 UTC
    As an aside, I'd note that comments are really only useful in conjunction with the user-level documentation. Maintainers needs to know both what the code is supposed to do and how it does it.

    Excellent points.

    Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents.

    Much (in a great way) like (similar to) a (singular article) sentence (grouping of words expressing an idea) doesn't (fails to) make (produce) sense (coherent meaning) without (lacking) the (definite article) definition (explanation of meaning) of (preposition) words (grouping of lettings expressing a concept).

    Make your reader's life easy by keeping the word definitions as close as possible to the words! It would be crazy to have a separate document that explains the basics and then to expect your copy editor to actually understand the meaning of English words before she jumps in trying to edit your sentences.

    Oh, some of my definitions above rather suck. I find that often happens when I'm forced to shift tasks in the middle of composing a sentence and throw together a word definition in order to get the boilerplate in place so I can type in the next word.

    - tye        

      Much (in a great way) like (similar to) a (singular article) sentence (grouping of words expressing an idea) doesn't (fails to) make (produce) sense (coherent meaning) without (lacking) the (definite article) definition (explanation of meaning) of (preposition) words (grouping of lettings expressing a concept).

      Make your reader's life easy by keeping the word definitions as close as possible to the words! It would be crazy to have a separate document that explains the basics and then to expect your copy editor to actually understand the meaning of English words before she jumps in trying to edit your sentences.

      Oh, some of my definitions above rather suck. I find that often happens when I'm forced to shift tasks in the middle of composing a sentence and throw together a word definition in order to get the boilerplate in place so I can type in the next word

      Touchy (french for bullseye)!

      The difference is it isn't like english prose, its more like dictionary

      =head2 C<< Much >> a definition =cut sub Much { "in a great way"; } =head2 C<< like >> a definition =cut sub like { "similar to"; } =head2 C<< a >> a definition =cut sub a { "singular article"; } =head2 C<< sentence >> a definition =cut sub sentence { "grouping of words expressing an idea"; } =head2 C<< doesn't >> a definition =cut sub doesn't { "fails to"; } =head2 C<< make >> a definition =cut sub make { "produce"; } =head2 C<< sense >> a definition =cut sub sense { "coherent meaning"; } =head2 C<< without >> a definition =cut sub without { "lacking"; } =head2 C<< the >> a definition =cut sub the { "definite article"; } =head2 C<< definition >> a definition =cut sub definition { "explanation of meaning"; } =head2 C<< of >> a definition =cut sub of { "preposition"; } =head2 C<< words >> a definition =cut sub words { "grouping of lettings expressing a concept"; }

        No. The difference is that you don't appear to look for the structure in code and so think of it as a bunch of unrelated definitions and so you don't appreciate how jarring it can be to have the structure of code (or documentation) so badly broken up.

        Your example above is like "boxing chess" or the Yazoo album Upstairs at Eric's: interleaving stripes of quite opposed types. And it wouldn't really matter if you had special colors assigned to help distinguish the stripes. (Except that "boxing chess" and an album are things that you almost always experience quite linearly so the transitions between stripes are quite few and even predictable.)

        The stripes still mean that you can't scan the documentation without having constant interruption of the non-documentation stripes breaking up your visual and mental parsing. Your eyes move a bit up or down on the page and your brain has to jump between "parse this Perl code" and "parse this documentation in POD format".

        Parsing of Perl code is all about punctuation. Parsing of POD is greatly about whitespace. Shifting gears between those modes is disruptive.

        Why that isn't a problem for sample code included in POD helps to illustrate why mixing real code and POD is a problem. Sample code is visually distinct in the context of POD. It is indented. It also is always quite short. If your sample code gets very long, then it really disrupts the structure and flow of the documentation.

        More importantly, it is also nested inside of the POD as a separate paragraph (or several paragraphs). And the primary structure of POD is separate paragraphs.

        Nested structures of different types is not a problem. I see a visual field structured around physical objects. One of those physical objects is a screen. Inside of that screen are a bunch of "windows". Inside one of those windows are a bunch of panels. Inside one of those panels is a bunch of POD. Inside that POD is a paragraph that is Perl code. Inside that Perl code is a regex. That all is easy to deal with.

        Including real code with POD is quite different. The real code doesn't have to be indented so you lose the visual distinction.

        More significantly, the real code isn't nested inside of the POD, it is just adjacent to it. The line between the two isn't defined by the outermost structure of POD nor by the outermost structure of code. So when you are scanning the POD at the outermost layer of its structure, you can very easily cross into real code without having noticed the line you crossed. Same for scanning real code.

        If you can stand the distraction (to me) of a whole rainbow of colors, then you can make it easy to tell that you crossed the line between POD (which is probably one color) and real code (which is probably tons of colors). But that doesn't fix the problem of adjacent rather than nested dissimilar outer structures.

        The color scheme doesn't form an outer structure (at least it wouldn't to me). A 'sub' or other "block" doesn't get assigned a single color. So the outer structure of real code is much broader than the finer structure of the syntax highlighting. So now we've gone to three different types of structure jumbled together.

        With some mental gymnastics, you can make this mishmash work by defining just "pink" (the example color for POD) vs. "not pink" as the outermost structure. Within "pink", the next layer of structure is the paragraphs of POD. Withing "not pink", the next layer of structures is the outer structure of code (likely an eclectic layer slightly wider than the "block" layer). After you go a few layers deeper into that "code" structure, then you get to the layer that matches the color scheme (minus "pink").

        I can understand how some people would be just fine with that rather fractured mental model and it would work well for them -- at least during those few source code tasks that they actually do from within their syntax highlighting editor and where the editor can know how to highlight the syntax.

        And, if you are reading linearly (and not scanning), then the shifts between stripes are likely quite gentle. And if you suck at grokking code structure in a more "all at once" manner, then even when you scan or jump around, you have to parse the code nearly linearly so you notice the jar from the stripes much less.

        But if you are parsing code or POD more holistically, then the competing outermost structures being mashed together in stripes can be maddeningly disruptive. It really feels very much like having the outer structure of "sentence" horribly broken up by shuffling definitions between each word (as I did just above).

        It is like looking at a room and seeing a couch next to a block of text that isn't part of any physical object next to a table next to... stripes of physical reality and stripes of "computer images" side by side with no sensible border between them... and trying to plan the physical layout for the party with the guest list "helpfully" made adjacent to reality in a way that gives your mind no sensible outer structure to apply (except it is worse because POD and code aren't even close to as visually distinctive as "reality" vs. "text").

        And it doesn't really matter that much that the text on the slices of computer screen that have impossibly shuffled themselves (between the slices of reality) is green while there isn't a single green physical object in the room. It still makes it jarring and difficult to figure out if the couch would look better over there.

        - tye        

Re^2: Documentation: POD vs Comments
by Anonymous Monk on Jul 22, 2011 at 13:41 UTC

    "Scattering POD inline with code is Good, putting it all at the beginning or end of the file, separate from what it's documenting, is Bad." -- DrHyde.

    Your "good" & "bad" situations are reverse for me. Please offer that as your personal preference but not as some kind of truth.

      Your "good" & "bad" situations are reverse for me. Please offer that as your personal preference but not as some kind of truth.

      Why? It is the truth according to DrHyde -- what theory of truth are you operating under?

        The quoted sentence was written without any qualifiers or disclaimers (as if everybody prefers that sentiment).