SQL 주석 헤더 예

SQL 주석 헤더 예

---

사람들의 저장 프로 시저 / 함수 등 주석 헤더가 어떻게 보이는지보고 싶습니다 (예제 게시) ... 저는 SQL Server Management Studio가 생성하는 것만 보았지만 다른 사람들의 모습에 관심이 있습니다 ... 서식, 사용 된 문자, 절차 정보 / 세부 사항 등이 정말 다른 점이라고 생각합니다.

SQL Server Management Studio (버전 9) 저장 프로 시저 주석 헤더 기본값 :

-- =============================================
-- Author:      Name
-- Create date: 
-- Description: 
-- =============================================

---

/******************************
** File:    
** Name:
** Desc:
** Auth:
** Date:
**************************
** Change History
**************************
** PR   Date        Author  Description 
** --   --------   -------   ------------------------------------
** 1    01/10/2008      Dan      added  inner join
*******************************/

---

--
-- 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.
--

---

우리는 이와 같은 것을 사용하고 저에게 매우 유용합니다.

/*  
Description:   
Author:   
Create Date: 
Param:   
Return:   
Modified Date:  
Modification:   
*/  

---

-------------------------------------------------------------------------------
-- 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.
-------------------------------------------------------------------------------

---

-- [why did we write this?]
-- [auto-generated change control info]

---

set timing on <br>
set linesize 180<br>
spool template.log

/*<br>
##########################################################################<br>
-- Name : Template.sql<br>
-- Date             : (sysdate) <br>
-- Author           :   Duncan van der Zalm - dvdzalm<br>
-- Company          :   stanDaarD-Z.nl<br>
-- Purpose          :   <br>
-- Usage        sqlplus <br>
-- Impact   :<br>
-- Required grants  :   sel on A, upd on B, drop on C<br>
-- Called by        :   some other process<br
##########################################################################<br>
-- ver  user    date        change  <br>
-- 1.0  DDZ 20110622    initial<br>
##########################################################################<br>
*/<br>

sho user<br>

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

---

나는이 포스트가 오래되었다는 것을 알고 있지만, 잘 포맷 된 코드는 결코 스타일을 벗어나지 않는다.

모든 절차에이 템플릿을 사용합니다. 어떤 사람들은 장황한 코드와 주석을 좋아하지 않지만 90 년대 중반 이후로 손대지 않은 저장 프로 시저를 자주 업데이트해야하는 사람으로서 잘 형식화되고 주석이 많은 코드를 작성하는 것의 가치를 말할 수 있습니다. 많은 사람들이 가능한 간결하게 작성되었으며 때로는 절차의 의도를 파악하는 데 며칠이 걸릴 수 있습니다. 코드 블록을 읽는 것만으로도 코드 블록이 수행하는 작업을 쉽게 알 수 있지만 적절한 주석없이 코드의 의도를 이해하는 것이 훨씬 어렵고 때로는 불가능합니다.

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

---

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.

---

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

*/

---

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

---

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.

*/*/*/

---

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
======================================================================== */

참고URL : https://stackoverflow.com/questions/1085672/sql-comment-header-examples