Archive for the ‘Perl’ Category

PBP: 098 Proofreading

Monday, June 1st, 2015

It is a Best Practice to check the spelling, syntax, and sanity of your documentation.  I agree with this, strongly. (more…)

PBP: 097 Discursive Documentation

Thursday, May 7th, 2015

The PBP suggests a way to put longer blocks of documentation in code, by using the =for or =begin/=end notation in POD.  By labeling these with a “formatter” that does not exist, they’ll never be output and are merely ignored by the compiler and for the author’s use. (more…)

PBP: 096 Indicative Documentation

Monday, May 4th, 2015

The Best Practices suggests that a need for a lot of comments explaining things might indicate that the section of code is confusing and could be written more clearly.  Rather than writing words to try and explain it, can the code itself be clearer? (more…)

PBP: 095 Defensive Documentation

Thursday, April 9th, 2015

This practice is simple, and probably covers a lot of the places I appear to have been waffling between one view and another.  The book says to comment anything that puzzled or tricked you.  Pretty simple?  The questionable part is that everyone will find different issues tricky. (more…)

PBP: 094 Elucidating Documentation

Monday, April 6th, 2015

The Best Practice discussed here is to use short comments at the end of the line to provide extra detail and make possibly obscure code a little clearer.  I think this can be very useful, but I’m not sure it plays well with a 78 character margin as suggested elsewhere, especially if the function involved is complex and you’re more than a couple of tab stops from the margin. (more…)

PBP: 093 Algorithmic Documentation

Thursday, March 26th, 2015

The Best Practices suggest using a full-line comment before a paragraph of code to explain the algorithm.  This is, in my experience, good advice, and what comments should be used for. (more…)

PBP: 092 Comments

Monday, March 23rd, 2015

The Best Practices suggest creating a template for block comments that are suitable for your team.  On the whole the reasons given in the book are good ones and it sounds like a great idea, but I find it harder to implement in practice. (more…)

PBP: 091 Technical Documentation

Thursday, March 19th, 2015

The Best Practices suggest breaking your documentation apart by audience.  Different audiences need different documentation.  It then goes on to suggest where this different documentation belongs… and that’s why my opinion diverges. (more…)

PBP: 090 Position

Monday, March 16th, 2015

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. (more…)

PBP: 089 Contiguity

Thursday, March 12th, 2015

The PBP likes documentation in POD, in your source files, but wants it all in one chunk, separated from the code it documents.  This is one of the suggestions in the PBP I not only disagree with, I find damaging. I feel strongly that the documentation goes as close to the code as possible, to minimize the distance between them and make the tendency to avoid updating them harder to forget. (more…)