Traits, r

[Andy Armstrong]

On 10 Feb 2008, at 19:25, muppet wrote:
>> 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.

Oh sure - I'm not suggesting peppering your code with nothing more than

# http://mysite.com/~bonzo/junk/some-shite.html

It needs context in the code - enough to work out what's going on if  
the link dies. But a couple of times lately I've read through a  
programmer's length explanation of what some code was supposed to do  
when

# This implements Spatchcock's tree invigorating algorithm
#   http://bleedingobvious.org/nuggets/invig-tree.html

would have done the trick. That's all I need assuming Spatchcock's  
method doesn't fall so completely from favour that I can't even Google  
for it in five years.

-- 
Andy Armstrong, Hexten