Tuesday, February 15, 2005

Code Documentation Humour

Here are some paragraphs from the perldoc of Class::MethodMaker Perl module. For some wonderful reason (that I'm yet to comprehend), the documentation of many open-source tools can be found to be garnished with some humour. This has the pleasent effect of making the documentation and the tool tastier and easier to ingest, for the mind.


Some new facilities may be marked as EXPERIMENTAL in the documentation. These facilities are being trialled, and whilst it is hoped that they will become mainstream code, no promises are made. They may change or disappear at any time. Caveat Emptor. The maintainer would be delighted to hear any feedback particularly regarding such facilities, be it good or bad, so long as it is constructive.

Some old facilities may be marked as COMPATIBILITY in the documentation. These facilities are being maintained purely for compatibility with old versions of this module, but will ultimately disappear. They are normally replaced by alter- natives that are thought preferable for some completely arbitrary raisin. Please avoid using them, and consider amending any existing code that does use them not to. If you believe that their removal will cast an unacceptable pall over your life, please contact the maintainer, or get a new life: whichever is easier.

You may also like to have a look at the poem entitled "Pipe Grep More", I had stumbled upon while having a look at the source of multi-protocol IM client GAIM 0.75 a long while ago.

Ah, I like the sound of Pipe Grep More, so I am going to rename my blog from "City of Code" to "PIPE GREP MORE" for a couple of days.