#####################################################
# RE: documenting methods/subs #
# version 0.01 #
# This note can be distributed under the same #
# terms as perl itself #
#####################################################
# paragraph 1
# This is my opening statement where i state my
# opinion on the afore mentioned node.
personally i go for more of a 'tabbed comments to the
right hand side of an ambiguous statement' Camel-type
documentation.
# paragraph 2
# some expansion on already stated opinions, and a
# little funny for some light relief
As you say, self-documenting is best - ideally there should
only be a need to briefly "comment" or refer to other parts
of the code. Otherwise, you probably dont know have a clear
concept of the what and why of what you are doing - in which
case, might as well keep schtum!
# paragraph 3
# my conclusion as to why code written in this format
# completely sucks and makes no contribution to coding
# productivity or ledgability
IMHO, using TAB/space to line up common features, liberal use
of newlines, and well named subs/variables is usually more than
sufficient to make code readable.
1; # PS i really hate it when people comment on 1;
-
Are you posting in the right place? Check out Where do I post X? to know for sure.
-
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big>
<blockquote> <br /> <dd>
<dl> <dt> <em> <font>
<h1> <h2> <h3> <h4>
<h5> <h6> <hr /> <i>
<li> <nbsp> <ol> <p>
<small> <strike> <strong>
<sub> <sup> <table>
<td> <th> <tr> <tt>
<u> <ul>
-
Snippets of code should be wrapped in
<code> tags not
<pre> tags. In fact, <pre>
tags should generally be avoided. If they must
be used, extreme care should be
taken to ensure that their contents do not
have long lines (<70 chars), in order to prevent
horizontal scrolling (and possible janitor
intervention).
-
Want more info? How to link
or How to display code and escape characters
are good places to start.
|