News for hackers. Stuff that matters.
Re:Readme Driven Development by c0ffeeadd1c7 on Monday August 23, 2010 @03:05PM (#1627678)
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)

[deleted]
Re:Readme Driven Development by jacquesm on Monday August 23, 2010 @06:58PM (#1628342)
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.
Re:Readme Driven Development by silentbicycle on Monday August 23, 2010 @10:52PM (#1628777)
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:

    /*******************
     * theFunctionName *
     *******************/
because 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.)