On Thu, Jun 25, 2009 at 05:00:27PM -0400, Hal Vaughan <h...@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 -- To UNSUBSCRIBE, email to debian-user-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
