in reply to Where to place POD

I find there is no good solution for all cases.

I want the POD to read as a coherent document, which is hard to ensure if it is broken up across the code. The ideal ordering of the methods/functions in the code is not always the same as the ideal ordering within the documentation.

On the other hand, 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 (resulting in them reading the code with incorrect assumptions about the intent), and much less likely to update the documentation when changing the code.

I guess I put them inline 90% of the time, the remaining cases are those where that would make it too hard to maintain the desired structure.

Hugo

Replies are listed 'Best First'.
Re^2: Where to place POD
by talexb (Chancellor) on Jan 15, 2024 at 04:27 UTC
      The ideal ordering of the methods/functions in the code is not always the same as the ideal ordering within the documentation.

    This! You may want to group the functions together in one way in the module, but prefer to structure the POD in a different way. This approach is easy when the POD's contained in a separate file from the code.

      .. 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. I can think of a number of modules that I've used where I've never looked at the code, but have re-read the POD lots of times.

      .. and much less likely to update the documentation when changing the code.

    It would be poor software craftsmanship to update the code without updating the POD. I would expect a PR that improves/alters the code for a module would include code, documentation, and some information about what the goal of the change is. And in the Perl world, backwards compatibility is really, really important.

    Alex / talexb / Toronto

    Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

[reply]

      .. 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.

[reply]
[d/l]
          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.

        Ah! If this is about people coming to update and/or fix the code, then I agree, they would look at the POD, and then go to the code.

        I was thinking more about the situation where someone needs to use a module to get something done, without thinking about 'Gee, how does this all work?'

        Alex / talexb / Toronto

        Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

[reply]
[d/l]

        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

        In my experience, it usually means they're both wrong. :-)

        Pop quiz: what would you do if you stumbled upon these two code snippets while making an unrelated bug fix?

        Case 1: 

        # Add one to $i
$i = $i + 1;

        [download]

        Case 2: 

        # Add one to $i
$i = $i - 1;

        [download]

        👁️🍾👍🦟
[reply]
[d/l]
[select]
      The POD should contain enough information for someone using the module to write code that uses it

      But this module currently only has me using it. As I said in the question, it is a utility module that will never be published. The reason I am adding POD is to help me remember what what all the methods do without having to keep diving into the source code to look at comments and inspect the code.

      We will almost certainly bring on another developer at some point. But even then, I don't expect this module will ever have the same level of POD detail as I would apply to a module that was destined for CPAN.

[reply]

In Section Seekers of Perl Wisdom