I know this post is ancient, but well formatted code never goes out of style.
I use this template for all of my procedures. Some people don't like verbose code and comments, but as someone who frequently has to update stored procedures that haven't been touched since the mid 90s, I can tell you the value of writing well formatted and heavily commented code. Many were written to be as concise as possible, and it can sometimes take days to grasp the intent of a procedure. It's quite easy to see what a block of code is doing by simply reading it, but its far harder (and sometimes impossible) is understanding the intent of the code without proper commenting.
Explain it like you are walking a junior developer through it. Assume the person reading it knows little to nothing about functional area it's addressing and only has a limited understanding of SQL. Why? Many times people have to look at procedures to understand them even when they have no intention of or business modifying them.
/***************************************************************************************************
Procedure: dbo.usp_DoSomeStuff
Create Date: 2018-01-25
Author: Joe Expert
Description: Verbose description of what the query does goes here. Be specific and don't be
afraid to say too much. More is better, than less, every single time. Think about
"what, when, where, how and why" when authoring a description.
Call by: [schema.usp_ProcThatCallsThis]
[Application Name]
[Job]
[PLC/Interface]
Affected table(s): [schema.TableModifiedByProc1]
[schema.TableModifiedByProc2]
Used By: Functional Area this is use in, for example, Payroll, Accounting, Finance
Parameter(s): @param1 - description and usage
@param2 - description and usage
Usage: EXEC dbo.usp_DoSomeStuff
@param1 = 1,
@param2 = 3,
@param3 = 2
Additional notes or caveats about this object, like where is can and cannot be run, or
gotchas to watch for when using it.
****************************************************************************************************
SUMMARY OF CHANGES
Date(yyyy-mm-dd) Author Comments
------------------- ------------------- ------------------------------------------------------------
2012-04-27 John Usdaworkhur Move Z <-> X was done in a single step. Warehouse does not
allow this. Converted to two step process.
Z <-> 7 <-> X
1) move class Z to class 7
2) move class 7 to class X
2018-03-22 Maan Widaplan General formatting and added header information.
2018-03-22 Maan Widaplan Added logic to automatically Move G <-> H after 12 months.
***************************************************************************************************/
In addition to this header, your code should be well commented and outlined from top to bottom. Add comment blocks to major functional sections like:
/***********************************
** Process all new Inventory records
** Verify quantities and mark as
** available to ship.
************************************/
Add lots of inline comments explaining all criteria except the most basic, and ALWAYS format your code for readability. Long vertical pages of indented code are better than wide short ones and make it far easier to see where code blocks begin and end years later when someone else is supporting your code. Sometimes wide, non-indented code is more readable. If so, use that, but only when necessary.
UPDATE Pallets
SET class_code = 'X'
WHERE
AND class_code != 'D'
AND class_code = 'Z'
AND historical = 'N'
AND quantity > 0
AND GETDATE() > DATEADD(minute, 30, creation_date)
AND pallet_id IN ( -- Only update pallets that we've created an Adjustment record for
SELECT Adjust_ID
FROM Adjustments
WHERE
AdjustmentStatus = 0
AND RecID > @MaxAdjNumber
Edit
I've recently abandoned the banner style comment blocks because it's easy for the top and bottom comments to get separated as code the updated over time. You can end up with logically separate code within comment blocks that say they belong together which create more problems than it solves. I've begun instead surrounding multiple statement sections with BEGIN ... END blocks, and putting my flow comments next to the first line of each statement. This has the benefit of letting you collapse code block and be able to clearly read the high level flow comments, and when you branch one section open you'll be able to do the same with the individual statements within. This also lends itself very well to heavily nested levels of code. It's invaluable when your proc start to creep into the 200-400 line range and doesn't add any line bulk to an already long procedure.
Expanded
Collapsed
