scott at asofyet.org
Sun Feb 10 19:25:38 GMT 2008
On Feb 8, 2008, at 10:03 AM, Andy Armstrong wrote:
> On 8 Feb 2008, at 14:41, Greg McCarroll wrote:
>> the trick is if you are using some concept that is new or different
>> make sure you
>> comment it and clearly show its advantages. even if you have to
>> add URL's to
>> articles about it. if later it becomes a standard in the community
>> of perl
>> programmers they can always remove your comments.
> As a tangent it surprises me how little URLs are used in comments.
> It seems that programmers often feel the need to provide their own
> précis right there when a link would be both less verbose in the
> code and more informative. Maybe people are reluctant to admit their
> sources, or feel the need to demonstrate comprehension of the
> subject - but the next person who comes along cares little about that.
In my experience, the code and the comment will outlive the validity
of any external reference material.
A comment should not be simply "http://example.com/explanatory/
page.html" --- include the important bits right there and use the URL
for the full story.
A commit message should not be simply "bug #12345" --- include a one-
The last thing you want is to be saying "wtf is going on here" and
have the only comment be a dead hyperlink or reference to a bug number
in a bug tracking system that was turned off five years ago.
I'd also rant about ten-year-old "temporary hack" comments, but that's
elysse: You dance better than some.
me: "Some" what?
elysse: Some asparagus.
More information about the london.pm