Traits, r

[muppet]

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[1]. 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- 
line synopsis.


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  
fairly pointless.


--
elysse:  You dance better than some.
me:  "Some" what?
elysse:  Some asparagus.