SP, UDF, Trigger 문서 자동화 하기

invalid-file

invalid-file

Stored Procedure, User Defined Function, Trigger와 같이 Programmable한 DB Object의 Document 관리는 어떻게 해야 할까?

 

여러가지 방법이 있겠지만, 개인적으로는 소스 코드의 주석과 Extended Property를 활용하는 방법을 선호한다. 즉, DB로부터 SP 정보를 추출하여 문서화하자는 얘기. (UDF, Trigger도 마찮가지)
 

첨부 파일의 샘플 SP를 등록하고… 실행하면, 아래와 같은 문서를 얻을 수 있다.

만약, sp_helpmodule에 아무런 인자도 주지 않는다면, 해당 DB 컨텍스트의 모든 module에 대한 문서가 작성된다.

 

EXEC sp_helpmodule 'P_AddExtraUser'

 

결과

=== dbo.P_AddExtraUser ===

 

- Summary

================================================================================================

author : Doeyull.Kim

e-mail : doeyull.kim@xxxxxx

created date : 2008-06-20

description : 기가입회원의새사용자ID를추가합니다.

return value :

0 = 에러가없습니다.

4010001 = 트랜잭션을Commit할수없는상태입니다.

4010100 = 시스템에러가발생하였습니다.

4010105 = 대상레코드를찾을수없습니다. [Members]

4010110 = 이미존재하는닉네임입니다.

4010111 = 사용자ID는최대3개까지만들수있습니다.

4010112 = 보호자동의가완료되지않았습니다.

4010120 = 여권확인이완료되지않았습니다.

4010121 = 이미등록된이메일주소입니다.

================================================================================================

 

- Usage

================================================================================================

DECLARE @intReturnValue int;

DECLARE

          @inyMemberIdentityCode tinyint      -- 1=주민등록번호, 2=외국인등록번호, 3=여권번호, 4=없음

        , @binMemberIdentity binary(32)       -- 암호화된주민등록번호또는외국인등록번호또는여권번호. memberIdentityCode로구분됩니다.

        , @vchUserID varchar(12)      -- 사용자ID.

        , @binSalt binary(10)  -- 암/복화화용Salt.

        , @binVerifier binary(64)     -- 회원패스워드인증자.

        , @nvcNickName nvarchar(50)   -- 닉네임.

        , @nvcEmail nvarchar(50)      -- 이메일.

        , @bitEmailReceiveFlag bit    -- 0=메일수신안함,1=메일수신.

        , @inyNativeRegionCode tinyint --

        , @inbUserSN bigint;   -- [Users]테이블의Primary Key.

 

SET @inyMemberIdentityCode = NULL;

SET @binMemberIdentity = NULL;

SET @vchUserID = NULL;

SET @binSalt = NULL;

SET @binVerifier = NULL;

SET @nvcNickName = NULL;

SET @nvcEmail = NULL;

SET @bitEmailReceiveFlag = NULL;

SET @inyNativeRegionCode = NULL;

 

EXEC @intReturnValue = dbo.P_AddExtraUser

          @inyMemberIdentityCode = @inyMemberIdentityCode

        , @binMemberIdentity = @binMemberIdentity

        , @vchUserID = @vchUserID

        , @binSalt = @binSalt

        , @binVerifier = @binVerifier

        , @nvcNickName = @nvcNickName

        , @nvcEmail = @nvcEmail

        , @bitEmailReceiveFlag = @bitEmailReceiveFlag

        , @inyNativeRegionCode = @inyNativeRegionCode

        , @inbUserSN = @inbUserSN OUTPUT;

 

SELECT @inbUserSN AS [@inbUserSN];

 

PRINT @intReturnValue;

================================================================================================

 

- Flow

================================================================================================

1. 트랜잭션을Commit할수없는상태이면, 롤백하고4010001을리턴합니다.

2. 회원정보를쿼리합니다.

        1. 회원정보가존재하지않으면4010105를리턴합니다.

        2. 14세미만내국인회원가입신청이후보호자동의가완료되지않은상태이면4010112를리턴합니다.

        3. 외국인회원가입신청이후여권확인이완료되지않은상태이면4010120를리턴합니다.

3. 회원이가진사용자ID 개수를쿼리하여, 현재3개이상이라면4010111을리턴합니다.

4. User를추가합니다.

        1. [Users] 테이블에INSERT합니다.

               1. 이미존재하는User ID이면4010106을리턴합니다.

        2. [UserInformations] 테이블에INSERT합니다.

               1. 이미존재하는닉네임이면4010110을리턴합니다.

               2. 이미등록된이메일이면4010121을리턴합니다.

5. 가입약관동의를기록합니다.

6. 메일수신에동의한경우메일링리스트에추가합니다.

        1. [MailingLists] 테이블에INSERT합니다.

        2. [MailingListLogs] 테이블에INSERT합니다.

================================================================================================

 

 

첨부한 sp_helpmodule을 활용하려면, 아래 나열한 주석 작성 규칙을 따라 SP나 UDF등을 작성해야한다.

 

1.     주석

A.     헤더

                                i.         /** 이곳에 헤더에 해당하는 주석 작성 **/

B.      샘플

/**

author : Doeyull.Kim

e-mail : doeyull.kim@xxxxxx

created date : 2008-06-20

description : 기가입회원의새사용자ID를추가합니다.

return value :

0 = 에러가없습니다.

4010001 = 트랜잭션을Commit할수없는상태입니다.

4010100 = 시스템에러가발생하였습니다.

4010105 = 대상레코드를찾을수없습니다. [Members]

4010110 = 이미존재하는닉네임입니다.

4010111 = 사용자ID는최대3개까지만들수있습니다.

4010112 = 보호자동의가완료되지않았습니다.

4010120 = 여권확인이완료되지않았습니다.

4010121 = 이미등록된이메일주소입니다.

**/

2.     소스 코드 중간 중간에서 로직을 설명하는 싱글 라인 주석

A.     --_로 시작하고, #을 이용해 번호를 매긴다. (위키 태그를 모방함 ^^;)

B.      샘플

--_# 첫째줄

--_## 둘째줄

--_### 셋째줄

--_## 넷째줄

--_# 다섯째줄

 

위와 같이 주석을 작성하면, sp_helpmodule에서 아래와 같이 파싱하여 보여준다.

 

1. 첫째줄

       1. 둘째줄

             1. 셋째줄

       2. 넷째줄

2. 다섯째줄

 

3.     Extended Property

A.     모듈 자체와 파라미터에 대해 extended property를 넣어준다.

B.      샘플

EXEC sp_addextendedproperty N'MS_Description', N'기가입회원의새사용자ID를추가합니다.', N'user', N'dbo', N'procedure', N'P_AddExtraUser';

EXEC sp_addextendedproperty N'MS_Description', N'사용자ID.', N'user', N'dbo', N'procedure', N'P_AddExtraUser', N'parameter', N'@vchUserID';