Документация
HTML CSS PHP PERL другое

Section 7.8.  Comments

 
Previous
Table of Contents
Next

7.8. Comments

Use block templates for major comments.

Create comment templates that are suitable for your team. For example, to internally document a subroutine or method, you might use something like:


    

    ############################################
    # Usage      : ????
    # Purpose    : ????
    # Returns    : ????
    # Parameters : ????
    # Throws     : no exceptions
    # Comments   : none
    # See Also   : n/a

which might be filled in like so:


    

    ############################################
    # Usage      : Config::Auto->get_defaults(  )
    # Purpose    : Defaults for 'new'
    # Returns    : A hash of defaults
    # Parameters : none
    # Throws     : no exceptions
    # Comments   : No corresponding attribute,
    #            : gathers data from each
    #            : attr_def attribute
    # See Also   : $self->set_default(  )

Structured comments like that are usually better than free-form comments:

    
    # This method returns a hash containing the defaults currently being
    # used to initialize configuration objects. It takes no arguments.
    # There isn't a corresponding class attribute; instead it collects
    # the necessary information from the various attr_def attributes. There's
    # also a set_default(  ) method.

Templates produce commenting that is more consistent and easier to read. They're also much more coder-friendly because they allow developers to simply "fill in a form". Comment templates also make it more feasible to ensure that all essential information is provided, and to identify missing information easily, by searching for any field that still has a ???? in its "slot".

Your team might prefer to use some other template for structured commentsmaybe even just this:


    

    ### CLASS METHOD/INSTANCE METHOD/INTERFACE SUB/INTERNAL UTILITY ###
    # Purpose:  ????
    # Returns:  ????

In this version, the type of subroutine can be specified by retaining one of the four titles, and only the essential information is recorded:


    

    ### CLASS METHOD ###
    # Purpose:  Defaults for 'new'
    # Returns:  A hash of defaults

Note that it's particularly useful to indicate how the subroutine is expected to be usedeither with a Usage: field, or with a title like CLASS METHOD. In Perl, the sub keyword is used to declare normal subroutines, class methods, instance methods, internal-use-only utilities, as well as the implementation of overloaded operators. Knowing which role (or roles) a particular subroutine is supposed to play makes it much easier to understand the subroutine, to use it correctly, and to maintain it.

A templated block comment like those recommended earlier should be used to document each component of a module or application. "Components" in this context means subroutines, methods, packages, and the main code of an application.

    Previous
    Table of Contents
    Next
    © 2000- NIV