There was a thread at Inline POD vs. EOF POD a while ago about the
joys of inline versus eof POD. While a lot of people seemed
to like inline, my strong sympathies go with the position
put forth by tye and Abigail that eof is better for
POD.
In particular I liked Abigail's explanation
of why inline is a problem. To it I can only add the point
that synchronization of POD and code should be far less of
a problem than synchronization of general comments and code.
The POD is about the public interface. Public interfaces
should not be changed as capriciously as code. If you
do change them, you need to track down all of the code that
used the old interface and change that as well. Compared
to that synchronization, modifying the POD is a small
cost.
Comments that need synchronization with code for me go
inline. There your point about distance is relevant. But
I strongly prefer having POD at the end of the file.
-
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.
|
