{"id":1627678,"user":"c0ffeeadd1c7","time":1282590312,"time_ago":"16 years ago","type":"comment","content":"

next to a README there should be at least one line of documentation for every function longer then three lines of code.

I like documentation-driven design - when I'm to write a long and complex routine I always write in pseudo-code-comments what I am to do.

This pseudo code usually ends up as the documentation of the routine (little grammar/language update might be needed)","comments":[{"id":1628338,"time":1282604176,"time_ago":"16 years ago","type":"comment","content":"[deleted]","deleted":true,"comments":[{"id":1628342,"user":"jacquesm","time":1282604305,"time_ago":"16 years ago","type":"comment","content":"

That's a holdover from the good old days when you had to search through 3\" of fanfold paper for your function, they become a bit easier to spot like that.","comments":[{"id":1628777,"user":"silentbicycle","time":1282618327,"time_ago":"16 years ago","type":"comment","content":"

Whoa sorry, I wouldn't have deleted the comment if I had seen your response. I had decided that I was just grumbling and it didn't add anything to the conversation.

More or less, I had said that I hate that kind of coding convention, because while it's well intentioned, in reality it mostly adds an incentive against extracting repetitive code out into new functions. Also, I'm tired of seeing comments that say:

    /*******************\n     * theFunctionName *\n     *******************/\n

\nbecause somebody's shortsighted coding conventions required it - they tend to camouflage comments that actually matter. If you need big headlines to find where your functions start, get a better editor. (But I'm sure that was less applicable a decade or two ago.)","comments":[],"comments_count":0,"level":2,"url":"item?id=1628777"}],"comments_count":1,"level":1,"url":"item?id=1628342"}],"comments_count":2,"level":0,"url":"item?id=1628338"}],"comments_count":3,"url":"item?id=1627678"}

Comment by c0ffeeadd1c7