Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

flower box comments

by mandog (Curate)
on Nov 17, 2003 at 06:20 UTC ( #307572=perlquestion: print w/ replies, xml ) Need Help??
mandog has asked for the wisdom of the Perl Monks concerning the following question:

Some folks in my group favor comments in this style:

#--------------------------------------------------------- # Function: get_records (taken from process_member.pl) # Arguments: DB handle # sql query string # Returns: result array of SQL query #--------------------------------------------------------- sub get_records { my ( $db_handle_ref, $sql ) = @_; my @recs; # [...] return @recs; }

I have doubts about this style. Perhaps there is some advantage I am missing ?

Comment on flower box comments
Download Code
Re: flower box comments
by Zaxo (Archbishop) on Nov 17, 2003 at 06:31 UTC

    Like indentation, I think they are a matter of local style. The advantage is they make an easily spotted pattern for documentation of a function in code that is intended to be desk-checked. The baroque kind of framing you show is trained into many eyeballs, in variations for dozens of languages.

    IMO, pod makes more sense for perl. Going directly from code comments to documentation is a fine thing.

    After Compline,
    Zaxo

Re: flower box comments
by PodMaster (Abbot) on Nov 17, 2003 at 06:33 UTC
    You're not missing anything, your group is misguided.
    =head2 get_records my @foo = get_records( $dbh , "select * from BAR..." ); =cut sub get_records { # ... }
    Now you run it through perldoc, pod2man, pod2text, pod2html ...

    Comments are not documentation ;)

    *links here*

    MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
    I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
    ** The third rule of perl club is a statement of fact: pod is sexy.

      I avoid documenting private subroutines with POD.

      POD implies public.

        POD only implies pod and sexy.
        =for private =head2 get_records my @foo = get_records( $dbh , "select * from BAR..." ); =cut =begin private =head2 get_records my @foo = get_records( $dbh , "select * from BAR..." ); =end private =cut

        MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"
        I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).
        ** The third rule of perl club is a statement of fact: pod is sexy.

Re: flower box comments
by Itatsumaki (Friar) on Nov 17, 2003 at 06:33 UTC

    A lot of monks here (and good programmers in general) favour terse comments directly in the code, along with substantial POD. They likely have the same doubts you do.

    I've used a style much like that for a long time, though. I was first exposed to it in a C-shop, and I have seen several advantages with it:

    • Maintenance programmers don't have to read code for every sub
    • Explicitly states the contract for a function/method
    • Leaves room for prose (e.g. ToDo lists, caveats the programmer notes, modification histories for non-CVS environments)
    • Clearly separates methods and routines from one another
    • Clearly separates general comments from comments about specific lines of code

    That said, the better I get at Perl programming, the more my comments tend towards brevity, so I'm pretty sure those wiser monks who dislike this style are on to something.

    -Tats
Re: flower box comments
by vacant (Monk) on Nov 17, 2003 at 06:34 UTC
    Well, sure. It specifies a consistent format, and the format reminds (or requires) the programmer to supply the necessary ingredients for maintainers who will come later. It seems to be missing a Description field, though. I have noticed that without a mandated format, coders will occasionally be lax in documenting functions. Possibly more important than which format is used, is to pick one and everyone follow it consistently. I don't know what your doubts are except, perhaps, that it is too elaborate. Personally, I like it, especially for a formal group project. An editor macro or template file will ease the pain, if you find it painful.
Re: flower box comments
by AcidHawk (Vicar) on Nov 17, 2003 at 06:52 UTC

    You don't say what your doubts are..?

    I have had to maintian some pretty nasty code ( not mine of course..;) ) that had "flower box comments" and found them invaluable as apposed to no comments... which I've had to maintian also...

    -----
    Of all the things I've lost in my life, its my mind I miss the most.
Re: flower box comments
by Roger (Parson) on Nov 17, 2003 at 07:11 UTC
    The commenting style your group uses is not bad, it states the purpose of the subroutine clearly. And it would not be hard to write a parser to extract documentations from the code either.

    Just a side note on the code shown -
    return @recs;
    Won't it be more efficient if return reference instead?
    return \@recs;

      It also would not be hard* to write a parser to extract POD from the code.

      * In the sense that someone else has already done it. :)

Re: flower box comments
by gjb (Vicar) on Nov 17, 2003 at 08:49 UTC

    This documentation format reminds me strongly of the one used by RoboDoc which I happen to like a lot since it can be used in almost any programming language (Perl, Java, C/C++, etc) and can generate output in HTML, XHTML, RTF and LaTeX.

    If you can't convert your group to POD (which I agree is best for Perl programmers), at least it might be worthwhile to introduce them to RoboDoc since without much change of format and effort will allow automatic generation of documentation.

    Hope this helps, -gjb-

Re: flower box comments
by EdwardG (Vicar) on Nov 17, 2003 at 10:06 UTC

    What I have seen is that this style of comment (in particular) tends to grow less accurate as it passes through iterations of maintenance. Eventually it becomes just wrong, for example referring to parameters that are no longer used, or describing the original purpose that no longer applies.

    And if you don't trust the comment, you have to read the code, and if you end up reading the code then why bother with this type of comment in the first place.

    It could also be argued that this style of comment is a form of code duplication, complete with the same maintenance issues. Of course I want to see helpful comments, particularly for dense or terse code, but frankly I've developed a form of comment-blindness, triggered by code like this:

    /********************************************** * Copyright: Moneygrubbers, inc 1982-1984 * * ALL RIGHTS RESERVED * * System: Custom IEBGENER for CICS T1 * * Name: MyFunction * * Created: 1 Jan 1982 * * Author: asmith * * Purpose: Apply foo algorithm to bar data * * Returns: bptr - ptr to modified bah * * Mod: asmith * * Mod Purpose: bar is now baz * * Mod Date: 2 Jan 1982 * * Parameters: bar - ptr to bar * * Parameters: baz - stack copy of bar * * Known bugs: none * * Other comments: Hello, World! * * Re-written by bjones 1998 * * Code Status: UNREVIEWED * *********************************************/

    (Exaggerated for dramatic effect)

Re: flower box comments
by hieronymus (Scribe) on Nov 17, 2003 at 12:52 UTC
    IMHO just the fact that you comment your code is laudable in and of itself. Too many times I have had to go in and update | manitain | and ultimately re-write sloppy, uncommented code and cursed the entire time at the lack of comments.

    I agree with the other monks that converting your comments to POD makes more sense, however, I find that "flower box" comments are invaluable to me and my colleagues. As I am the only Perl coder in my group of admins (a mix of *nix and Win32) and the only fervently open-source coder, I find that this style of commenting lends itself to an easier interpretation for non-Perl coders (especially when most on the team don't even know what a perldoc is).

    -hieronymus
Re: flower box comments
by Ninthwave (Chaplain) on Nov 17, 2003 at 14:24 UTC

    I comment like the above. I borrowed this style from my learning back in the 80's and it was how most languages I learned suggested you comment. I hated comments, until I found myself programming in work. And had to revisit my own code. I specifically want to comment on functions and subroutines so I know what arguments and values are returned. This is easy for me as I update a function or subroutine I update the comment and know what the changes are and can quickly check the calls to the subroutine or function.

    That said when the script goes live and I am no longer testing it, I trim down the comments and place them in more approiate places for the documentation. POD I am just beginning to explore fully and can not list all its advantages as I was introduced to pod as a means of creating user help files pod2usage. Though from coming here I am starting to see its full nature.

    I think in general any commenting that is detailed is great. Converting it to other version is not hard. It would be easy to parse these scripts and change the commenting style. Remember commenting has set formats that perl needs to recognise to not execute comments. You can program a perl script to change your comments when the commenting style changes. So any commenting style can be updated if the need if you find the need to change style later.

    So in the style of commenting I believe pod looks like the most flexible way to make your comments useful on many levels. On the decision to mark each function in the code, I appreciate that decision and highly second it.

    Update I found this link but specifically an interesting comment on 2 pod || !2 pod:
    Canta Forda Computer Laboratory

    "No matter where you go, there you are." BB
Re: flower box comments
by adrianh (Chancellor) on Nov 17, 2003 at 15:01 UTC

    I have my doubts about this style too :-)

    #--------------------------------------------------------- # Function:   get_records (taken from process_member.pl) # Arguments:  DB handle #             sql query string # Returns:    result array of SQL query #--------------------------------------------------------- sub get_records {    my ( $db_handle_ref, $sql ) = @_;    my @recs; # [...]    return @recs; }

    Several issues:

    First off, as several other people have pointed out, if this is documentation aimed at the users of the code then POD would be the preferred format. That way you get the support of a lot of POD:: modules for formatting and reading your documentation.

    Second, look at what the comments tell you - or rather what they don't:

    # Function:   get_records (taken from process_member.pl)

    The function name and the filename it lives in. Both of which we already know (we're looking at the file to see the comment, and the subroutine name is part of the subroutines declaration.)

    # Arguments:  DB handle #             sql query string

    The arguments are a database handle (to what?) and an SQL query string (of what format?). This gives us no more information that we would get from the first line of the function:

       my ( $db_handle_ref, $sql ) = @_;

    It would be even easier if we called the database handle $dbh which would be familiar to all users of DBI, and a more descriptive name for the sql query.

    Finally this:

    # Returns:    result array of SQL query

    Tells us, I think, that we get an array of the rows returned by the SQL query. This is:

    • Phrased badly. I could read that as an array of SQL query objects rather than the results from the SQL query.
    • It doesn't tell me what array consists of. Is it an array of hashes keyed of column names? An array of values in order? What?

    All of this information is better expressed in the code itself. Rather than spending time writing comments that can easily get out of sync with the code, spend time writing clear expressive code. If you can't look at a subroutine and understand what it does rewrite it until you do. Break it into smaller subroutines, use better subroutine names, use better variable names, etc.

    For example the original routine might be better expressed as (guessing it's actual use since the comment doesn't actually say :-)

    sub fetch_matching_process_records {    my ( $dbh, $sql_query ) = @_;    my @process_records; # Something that populates @process_records with # ProcessRecord objects with a known API    return @process_records; }
Re: flower box comments
by bluto (Curate) on Nov 17, 2003 at 18:36 UTC
    The main things I like about these types of comments are that they allow the reader to determine ...

    - Assumptions that the routine makes (e.g. a resource is locked by the caller before the routine is called; the routine isn't called very often so performance is not important and the implementation is simplified). Obviosly, you'll want to put in assertion-like sanity checks to handle these whenever you can, but there are cases where this is not possible and these may be buried (hence obfuscated) in the code.

    - Limitations of the implementation and future changes that could be made. Many times this is something like an idea of how to improve performance (i.e. by introducing some complexity) if an assumption changes about how the routine will be used in the future.

    Unfortunately, some project management types who believe that "more == better" get real pedantic and start mandating that all sorts of useless drivel appear here that is either quickly outdated and/or can be gleaned from the first two lines of the sub.

    bluto

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://307572]
Approved by Zaxo
Front-paged by bart
help
Chatterbox?
and the web crawler heard nothing...

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

    Is guessing a good strategy for surviving in the IT business?





    Results (56 votes), past polls