andy at hexten.net
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
> 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
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 london.pm