.. my experience is that if the documentation is not next to the code, people are much less likely to read the documentation when looking at the code ..

Mmm, that's a matter of opinion. The POD should contain enough information for someone using the module to write code that uses it. If they also have to look at the code, that's a problem with the POD.

Hmm, I'm not sure I agree that my experience is a matter of opinion. :)

If someone comes to read the docs, I would usually expect that they'll use perldoc or similar. This is about people coming to look at the code.

A typical workplace example is that a developer picks up a bug report, analyses it to the point they see a method call somewhere clearly expecting some behaviour, and sees in the method that it does not implement that behaviour. They then make an assumption (effectively a guess) about whether it's the call or the implementation that is wrong, rather than determining that from the documentation of the method. Having the documentation right there when they look at the implementation is one small way to help them avoid that error.

It would be poor software craftsmanship to update the code without updating the POD.

Yes. Sadly, some human software developers are not perfect. We should do what we can to help them overcome their imperfections - to make it as easy as possible to do things right. Having docs next to the code it describes is one small way to make it easier to do things right.

In reply to Re^3: Where to place POD by hv
in thread Where to place POD by Bod

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.