The flower box in code is absolutely essential and just about the only place where documentation won't accidentally get lost. Someone would have to make an effort to delete it. I'd place no maximum limits there or on comments in the code.
See the code in the following article for the way I actually write a flower box in the code. It contains the basic purpose, usage, programmer notes, and revision history. If it has dependencies, I'll sometimes include those depending on what it is. There are some places where you shouldn't have to document essential tribal knowledge in every piece of code you write.
More than in the flower box, especially for stored procedures, I believe that if you cannot write a simple comment to explain what each and every SELECT (or whatever) does, then you've not done it right. I worked at a company where all of the stored procedures and other code objects had absolutely zero comments. On a large, complex stored procedure, it would take someone two days to do all of the research necessary to make a rather simple modification and then they'd get the modification wrong and it would come back from QA as broken. I told folks to start writing comments in all new code and any piece of legacy code they touched. It didn't actually slow things down much because all they had to do was write a simple comment after they figured out was a "segment" of code was doing.
The benefits were immediate on the code that was quickly documented. After two years, all of the code had been documented. Research time dropped from around 1-2 days to about 10-60 minutes and we came damned close to having a zero defect environment, which also allowed us to push out code faster than ever because rework after a QA failure (or, worse, a production failure) takes 8 times longer to find and fix the problem than it does to do it right the first time every time.
is pronounced "ree-bar
" and is a "Modenism
" for R
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column.
"If you think its expensive to hire a professional to do the job, wait until you hire an amateur."--Red Adair
"Change is inevitable... change for the better is not."
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)