On 06/21/2010 05:38 PM, Kieren Diment wrote:
On 21/06/2010, at 11:48 PM, Sir Robert Burbridge wrote:
Out of a discussion last week, I have some code to contribute (largely to
Catalyst::Helper).
Two quick questions:
[snip q 1 ]
2) I've noticed many times in the CPAN modules I've looked through tend to be
very sparsely commented (disregarding POD). I tend to do a fair bit of inline
comments (maybe about 1:2 comments:code). Is there some reason I should keep
comments sparse in contributed code?
If you're contributing a to CPAN, then you're almost certainly contributing a
reusable library. As a potential user of your library, I as a rule will want
to avoid reading your source code if at all possible (there are people who
don't feel this way, and code where this approach can be an exception, but for
widest use, make this assumption). Given this, please ensure the POD you
contribute is reasonably complete.
However, I can see a role for comments in a Catalyst::Helper extension to
provide educational information for other people wanting to contribute to the
helper modules, so if you want to take this approach, then by all means give it
a go.
Yeah, I generally do two kinds of documentation:
* Comments provide engineering information
* POD provides API information
The two are for different purposes and targeted towards different audiences.
-Sir
_______________________________________________
List: [email protected]
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/[email protected]/
Dev site: http://dev.catalyst.perl.org/
