[Catalyst] Contributing code

[Sir Robert Burbridge]

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