On Mon, 21 Jun 2010, Sir Robert Burbridge wrote:
=>On 06/21/2010 10:19 AM, Ævar Arnfjörð Bjarmason wrote:
=>> On Mon, Jun 21, 2010 at 13:48, Sir Robert Burbridge<rburb...@cisco.com>
=>> wrote:
=>>
=>> > Out of a discussion last week, I have some code to contribute (largely to
=>> > Catalyst::Helper).
=>> >
=>> > Two quick questions:
=>> >
=>> > 1) I've never contributed code to a project outside my work before. How
=>> > do
=>> > I go about it?
=>> >
=>> Have you read http://wiki.catalystframework.org/wiki/contrib ?
=>>
=>>
=>I hadn't -- thanks, that's what I needed to find.
=>> > 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?
=>> >
=>> It depends on what sort of comments you're making. Comments that
=>> explain tricky code that help with maintenance down the road are
=>> welcome everywhere. If you're just making comments that help someone
=>> completely unfamiliar with Catalyst to read the code it'll probably be
=>> more distracting than helpful to core devs.
=>>
=>
=>Hmmm ok. Tough call. I tend to explain rationale and ramifications more than
=>describe the code. I'll try to keep everything terse (and I don't mind if the
=>comments get removed by cooler heads =)
=>
=>
Rationale and ramifications (assumptions, etc), in my experience are much
more important than basic comments explaining the code or an attempt to
inject humor or hubris--which tends to be the average case.
Better to have cogent 'Whys' any day so I say put them all in and if you
get enough complaints, they're easy enough to remove.
--
- Dwalu
.peace
--
I am an important person in this world -
Now is the most important time in my life -
My mistakes are my best teachers -
So I will be fearless.
- Student Creed_______________________________________________
List: Catalyst@lists.scsys.co.uk
Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/
Dev site: http://dev.catalyst.perl.org/
