Perl Best Practices [Electronic resources] نسخه متنی

اینجــــا یک کتابخانه دیجیتالی است

با بیش از 100000 منبع الکترونیکی رایگان به زبان فارسی ، عربی و انگلیسی

Perl Best Practices [Electronic resources] - نسخه متنی

Damian Conway

| نمايش فراداده ، افزودن یک نقد و بررسی
افزودن به کتابخانه شخصی
ارسال به دوستان
جستجو در متن کتاب
بیشتر
تنظیمات قلم

فونت

اندازه قلم

+ - پیش فرض

حالت نمایش

روز نیمروز شب
جستجو در لغت نامه
بیشتر
لیست موضوعات
توضیحات
افزودن یادداشت جدید







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.


/ 317