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…)
Author Archive
PBP: 092 Comments
Monday, March 23rd, 2015PBP: 091 Technical Documentation
Thursday, March 19th, 2015The 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, 2015The 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, 2015The 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…)
PBP: 088 Location
Monday, March 9th, 2015The Best Practices suggest putting your documentation in your source files, and provides some reasons. This is okay. (more…)
PBP: 087 Extended Boilerplates
Thursday, March 5th, 2015The Best Practices make some suggestions on additional things to include in your POD, and suggest those items get listed in your general boilerplates to fill out. Some of the suggestions are interesting, but I’m not sure they belong in every POD ever. (more…)
PBP: 086 Boilerplates
Monday, March 2nd, 2015The Best Practices suggest creating boilerplates for POD documentation. They helpfully provide some examples, and suggest differentiating between modules and applications. I can’t argue with these ideas, particularly when trying to get a group to standardize on a set, but they are not as clear-cut wins in my mind as the book make them out to be. (more…)
Cross Platform Perl Talk Abstract
Thursday, February 26th, 2015I am submitting a talk to this year’s YAPC::NA. It’s a talk I’ve given a couple of times, and has been well received. The submission form wants a URL for the abstract, and this was the most straightforward way I could think of to put it up. Feedback is welcome, even if the talk itself is not accepted. (more…)
PBP: 085 Types of Documentation
Thursday, February 26th, 2015This Practice starts off a new section, on documentation. I think there’s at least one point in this chapter I disagree with Mr. Conway’s conclusions, but we’ll get there presently. In general, I think he has valuable things to say, and the issues are worth thinking about and deciding on.
Documentation is important, and it’s something many of us are terrible at.
The first Practice he suggests is to be aware there are several kinds of documentation, and to separate the user documentation from the technical documentation. (more…)
PBP: 084 Loop Labels
Monday, February 23rd, 2015The PBP suggests applying a label to each loop that is exited explicitly. A simple request, but one I usually find vexing. (more…)