Re: Goodbye debian

[Daniel Burrows <dburrows@debian.org>]

On Thu, Jun 25, 2009 at 05:00:27PM -0400, Hal Vaughan <hal@halblog.com> was heard to say:
> Also, by the time I started using Java, I had learned that many times  
> when I write something, I'm revisiting later and have forgotten it, so  
> making sure my Javadoc comments were clear enough that I wouldn't have  
> to dig up the code just re-enforced that. I'm still surprised at the  
> number of uncommented regex stuff I see in Perl.  If I'm using a regex  
> that has ANY degree of complexity (other than pulling out, say, one  
> string with a wildcard or two), then I comment that line of code  
> specifically.

  I developed the habit of writing Doxygen (C++ version of Javadoc)
comments for all my code after an internship where that was a "house
rule".  I kept it up in large part because I found that writing API
documentation *made my code better*.  If I've divided the functionality
well, most of the subroutines should be able to be documented precisely
in a couple sentences; knowing I'm going to write a doccomment is a
good incentive to divide things sensibly and not have functions that are
a horrible mishmash of orthogonal concerns. :-)

  Daniel