SQL comment header examples

Question

Would just like too see what peoples Stored Procedure Function etc comment headers look like  so post your examples    I ve only really seen what the SQL Server Management Studio creates but am interested in what other peoples look like   the formatting  characters used  procedure information details etc I guess are what really makes them different     SQL Server Management Studio  version 9  stored procedure comment header default   --                                               -- Author       Name -- Create date   -- Description   --

User · Answer

-- -- STORED PROCEDURE --     Name of stored procedure  -- -- DESCRIPTION --     Business description of the stored procedure s functionality  -- -- PARAMETERS --      InputParameter1 --           Description of  InputParameter1 and how it is used  -- -- RETURN VALUE --         0 - No Error  --     -1000 - Description of cause of non-zero return value  -- -- PROGRAMMING NOTES --     Gotchas and other notes for your fellow programmer  -- -- CHANGE HISTORY --     05 May 2009 - Who --          More comprehensive description of the change than that included with the --          source code commit message  --

User · Answer

-- Author   -- -- Original creation date   -- -- Description

User · Answer

Here s what I currently use  The triple comment                 is for an integration that picks out header comments from the object definition               Name            pr ProcName     Author          Joe Smith     Written         6 15 16     Purpose         Short description about the proc       Edit History    6 15 16 - Joe Smith                           Initial creation                      6 22 16 - Jaden Smith                           Change source to blahblah                           Optimized JOIN                     6 30 16 - Joe Smith                           Reverted changes made by Jaden

User · Answer

See if this suits your requirement           Notes on parameters  Give the details of all parameters supplied to the proc      This procedure will perform the following tasks    Give details description of the intent of the proc      Additional notes   Give information of something that you think needs additional mention  though is not directly related to the proc      Modification History    07 11 2001    ACL    TICKET BUGID        CHANGE DESCRIPTION

User · Answer

set timing on  lt br gt  set linesize 180 lt br gt  spool template log     lt br gt                                                                             lt br gt  -- Name   Template sql lt br gt  -- Date                sysdate   lt br gt  -- Author               Duncan van der Zalm - dvdzalm lt br gt  -- Company              stanDaarD-Z nl lt br gt  -- Purpose               lt br gt  -- Usage        sqlplus  lt br gt  -- Impact     lt br gt  -- Required grants      sel on A  upd on B  drop on C lt br gt  -- Called by            some other process lt br                                                                            lt br gt  -- ver  user    date        change   lt br gt  -- 1 0  DDZ 20110622    initial lt br gt                                                                             lt br gt     lt br gt   sho user lt br gt   select name from v database   select to char sysdate   Day DD Month yyyy HH24 MI SS    Start time  from dual     -- script   select to char sysdate   Day DD Month yyyy HH24 MI SS    End time  from dual    spool off

User · Answer

Here is my preferred variant                                                                            DESC    Some notes about what this does            tabbed in if you need additional lines NOTES   Additional notes            tabbed in if you need additional lines

User · Answer

We use something like this and very useful for me         Description     Author     Create Date   Param     Return     Modified Date    Modification

User · Answer

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                      quot what  when  where  how and why quot  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  lt - gt  X was done in a single step  Warehouse does not                                         allow this  Converted to two step process                                          Z  lt - gt  7  lt - gt  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  lt - gt  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  gt  0     AND GETDATE    gt  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  gt   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

User · Answer

--  why did we write this   --  auto-generated change control info

User · Answer

------------------------------------------------------------------------------- -- Author       name -- Created      date -- Purpose      description of the business technical purpose --              using multiple lines as needed -- Copyright    yyyy  Company Name  All Rights Reserved ------------------------------------------------------------------------------- -- Modification History -- -- 01 01 0000  developer full name   --      A comprehensive description of the changes  The description may use as  --      many lines as needed  -------------------------------------------------------------------------------

User · Answer

The header that we currently use looks like this   --------------------------------------------------- -- Produced By     Our company   -- URL         www company com   -- Author          me    -- Date        yesterday     -- Purpose         to do something   -- Called by       some other process    -- Modifications   some other guy - today - to fix my bug    ------------------------------------------------------------   On a side note  any comments that I place within the SQL i always use the format      Comment     As in the past I had problems where scripting  by SQL Server  does funny things wrapping lines round and comments starting -- have commented out required SQL     but that might just be me

[sql] SQL comment header examples

Examples related to sql

Examples related to comments