[Catalyst] Contributing code

[Dwalu Z. Khasu]

On Mon, 21 Jun 2010, Sir Robert Burbridge wrote:

=3D>On 06/21/2010 10:19 AM, =C6var Arnfj=F6r=F0 Bjarmason wrote:
=3D>> On Mon, Jun 21, 2010 at 13:48, Sir Robert Burbridge<rburbrid at cisco.co=
m>
=3D>> wrote:
=3D>>    =

=3D>> > Out of a discussion last week, I have some code to contribute (larg=
ely to
=3D>> > Catalyst::Helper).
=3D>> >
=3D>> > Two quick questions:
=3D>> >
=3D>> > 1)  I've never contributed code to a project outside my work before=
.  How
=3D>> > do
=3D>> > I go about it?
=3D>> >      =

=3D>> Have you read http://wiki.catalystframework.org/wiki/contrib ?
=3D>>
=3D>>    =

=3D>I hadn't -- thanks, that's what I needed to find.
=3D>> > 2)  I've noticed many times in the CPAN modules I've looked through=
 tend
=3D>> > to
=3D>> > be very sparsely commented (disregarding POD).  I tend to do a fair=
 bit of
=3D>> > inline comments (maybe about 1:2 comments:code).  Is there some rea=
son I
=3D>> > should keep comments sparse in contributed code?
=3D>> >      =

=3D>> It depends on what sort of comments you're making. Comments that
=3D>> explain tricky code that help with maintenance down the road are
=3D>> welcome everywhere. If you're just making comments that help someone
=3D>> completely unfamiliar with Catalyst to read the code it'll probably be
=3D>> more distracting than helpful to core devs.
=3D>>    =

=3D>
=3D>Hmmm ok.  Tough call.  I tend to explain rationale and ramifications mo=
re than
=3D>describe the code.  I'll try to keep everything terse (and I don't mind=
 if the
=3D>comments get removed by cooler heads =3D)
=3D>
=3D>
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