Traits, r

Andy Armstrong andy at
Sun Feb 10 19:46:44 GMT 2008

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 " 
> " --- 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


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  

# This implements Spatchcock's tree invigorating algorithm

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

More information about the mailing list