3 ms·
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 - wh
by c0ffeeadd1c7 16y ago
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 16y ago[deleted]
- jacquesm 16y agoThat'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.
- silentbicycle 16y agoWhoa 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.)