SQLコメントヘッダーの例
人々のストアドプロシージャ/関数などのコメントヘッダーがどのように見えるかを見てみたいです（あなたの例を投稿してください）...私は本当にSQL Server Management Studioが作成するものを見ましたが、他の人々がどのように見えるかに興味があります...書式設定、使用する文字、手順情報/詳細などが実際にそれらを異なるものにしていると思います...
SQL Server Management Studio（バージョン9）ストアドプロシージャのコメントヘッダーのデフォルト：
-- =============================================
-- Author: Name
-- Create date:
-- Description:
-- =============================================
これらすべての「変更履歴」フィールドと「変更日」フィールドは、プログラマーによってコードに埋め込まれるのではなく、バージョン管理ソフトウェアから取得でき、また取得する必要があることを指摘できますか。これは、C（たとえば）プログラマーがずっと前に学んだ教訓です。
/******************************
** 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年代半ばから触れられていないストアドプロシージャを頻繁に更新する必要がある人として、適切にフォーマットされ、コメントの多いコードを書くことの価値をお伝えします。多くは可能な限り簡潔になるように書かれており、手順の意図を把握するのに数日かかることがあります。コードのブロックが何をしているのかを単に読むだけで確認するのは非常に簡単ですが、それよりもはるかに難しい（そして時には不可能な）ことは、適切なコメントなしでコードの意図を理解することです。
ジュニア開発者にそれを説明しているように説明してください。それを読んでいる人は、それがアドレスしている機能領域についてほとんど何も知らず、SQLの限られた理解しか持っていないと仮定します。どうして？多くの場合、人々は手順を見て、それらを変更する意図やビジネス上の変更がない場合でも、それらを理解する必要があります。
/***************************************************************************************************
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.
***************************************************************************************************/
このヘッダーに加えて、コードには上から下までコメントとアウトラインが必要です。次のような主要な機能セクションにコメントブロックを追加します。
/***********************************
** Process all new Inventory records
** Verify quantities and mark as
** available to ship.
************************************/
最も基本的なものを除くすべての基準を説明する多くのインラインコメントを追加し、常にコードを読みやすいようにフォーマットします。インデントされたコードの長い垂直ページは、幅の広い短いページよりも優れており、数年後に他の誰かがコードをサポートしているときにコードブロックの始まりと終わりを簡単に確認できます。インデントされていない幅の広いコードの方が読みやすい場合があります。その場合は、必要な場合にのみ使用してください。
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
現在使用しているヘッダーは次のようになります。
---------------------------------------------------
-- 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
------------------------------------------------------------
補足説明として、SQL i内に配置するコメントは常に次の形式を使用します。
/ *コメント* /
過去のように、スクリプト（SQL Serverによる）が行を折り返し、コメントを開始するというおかしなことをするという問題がありました-必要なSQLをコメントアウトしています...
これが要件に合っているかどうかを確認します。
/*
Notes on parameters: Give the details of all parameters supplied to the procThis procedure will perform the following tasks: Give details description of the intent of the procAdditional notes: Give information of something that you think needs additional mention, though is not directly related to the procModification History: 07/11/2001 ACL TICKET/BUGID CHANGE DESCRIPTION
*/
私が現在使用しているものは次のとおりです。トリプルコメント（/ */*/*）は、オブジェクト定義からヘッダーコメントを選択する統合用です。
/*/*/*
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.
*/*/*/
私の好みのバリアントは次のとおりです。
/* =====================================================================
DESC: Some notes about what this does
tabbed in if you need additional lines
NOTES: Additional notes
tabbed in if you need additional lines
======================================================================== */
-- Author:
--
-- Original creation date:
--
-- Description: