Please note that the synopsis sections of CPAN modules are not code - they are documentation that has the form of code.
They only become code if you use something like Pod::Snippets to actually turn it into code.
And as useful as they are, I found that they already are a maintenance burden, and I'd prefer a non-copy-and-paste way to assemble them, if possible. (So far I haven't found one, but I also admit that I didn't look all that close). | [reply] |
You can call it documentation - but it is reuse of the ideas of the author. This may make the title of my medidation not quite correct - but these are just word-plays - what is important is the big picture of reuse.
Pod::Snippets is very interesting here - it is about having examples with tests. I believe this is a powerful idea. There are many modules at CPAN that are really just examples with thests. For example there are modules that 'adopt' something to use with Catalyst, but they don't really give any new functionality just rename things - and make sure that they work with Catalyst. I don't like the result - it adds another redirection layer that does nothing, and often even restricts the original interface. If it was presented as an example with tests users would get all the benefits with none of these disadvantages.
| [reply] |
Thanks for joining the discussion. One note - everybody knows that 'cut and paste' is evil - but yet there is a case where everyone would agree that it is not - on the contrary - it is the way to go for short examples like the synopsis in most CPAN modules.
Well, any sort of code template is essentially automated cut-and-paste. If you run h2xs or Module::Starter, you'll get an outline of code to start working with... and myself, I used to use some emacs code to generate perl accessors as needed.
The distinguishing feature of cut-and-paste vs. code abstraction is that with C&P you get a starting point that can be mutated at will without fear of effecting any other uses. The advantage of code abstraction is that if the interface is well designed, and well understood, you can often fix bugs by changing just one place in the code... but you'd better have good tests and/or QA, or you might have accidentally broken a use case without realizing it.
C&P has a bad reputation because it's too easy to do, and beginning programmers often produce large piles of C&P'd
crap that's exceedingly difficult to read, let alone maintain.
| [reply] |
| [reply] |
What I would say is you should use code abstraction by default, and resort to templates only to automate frequent coding tasks that resist that kind of code abstraction.
Really, we've all got "code templates" in our head, and there's no point making us type them over and over again...
| [reply] |