PBP: 090 Position

The PBP suggests keeping all the POD at the end of the file.  Considering I feel it should be with the code, I naturally disagree.

I feel the documentation belongs with the code.  Not nearby the code, but right there with the code itself.  There are some techniques that try and make this literally true, and I think they’re interesting.  I don’t know if they’re workable, but they’re interesting.

If the document is organized properly to make the system clear, why would the code not make sense in that order?  The argument made by many is that they don’t want to have to structure the code to support the documentation.  I don’t find that a compelling argument, and find it more important the two be together so they can easily be reviewed and maintained.

Leave a Reply