Naming Conventions

File Naming Conventions

PL/SQL이나 SQL에서 코드를 저장할 때 다음과 같은 확장자를 사용한다. Oracle Object 타입별로 확장자를 사용함으로써 Toad 같은 툴에서 해당 에디터를 바로 실행시킬 수 있으며, 향후 Version Control 시스템과 연동하기도 유리하다. 또한, Object의 유지관리 및 editplus 같은 편집기에서 해당 확장자별로 Syntax Coloring 을 적용하기도 유리하다.

표 1 File Name Convention

Variable Names < Identifier elements>

일반적으로 변수명은 다음과 같은 5가지 요소로 구성되어진다. <Scope><Type><Primary Identifier><Modifier><Suffix> 하지만, 본 가이드에서는 <Scope><Type>을 하나의 <Prefix>로 구성하여 <Prefix><Primary Identifier>로 변수명을 구성한다.

변수명의 CASE는 prefix<소문자>_Primary Identifier<Camel Case>와 소문자 + '_'로 구성한다. CamelCase가 원칙이며, 오라클 변수 스타일인 소문자와 underbar(_)만으로 연결된 변수 스타일도 허용한다. 예) v_SiteCode(O), v_site_cd (o)

Prefix

글로벌 변수 : 'g_' + Primary Identifier

글로벌 변수는 주로 패키지 레벨에서 사용되며, private, public 변수에 상관없이 g 접두어를 사용한다. 예) g_ErrorText, g_SiteCode

로컬변수 : 'v_' + Primary Identifier

로컬변수는 로컬식별자인 l 과 변수식별자인 v로 합쳐서 구성할 수도 있으나, 변수식별자인 v만용 사용하여 작성한다. 예) ), v_SiteCode(O), lv_SiteCode(X), l_SiteCode(X)

파라미터변수 : 'p_' + Primary Identifier

주로 프로시저나 함수의 파라미터에 사용되며 접두어 p를 사용한다. in 파라미터, out 파라미터에 대한 suffix는 사용하지 않는다. 예) p_SiteCode(O), p_ProductModelCode(O), p_SiteCode_out (X)

상수 : 'K_' + Primary Identifier

상수는 접두어K를 사용한다. 일반적으로 c_를 사용할 수도 있으나, c는 cursor 변수인 경우에 사용하며 상수의 경우에는 K_를 사용한다. 상수의 경우에는 일반적인 코딩 관습에 따라 예외적으로 대문자로만 변수명을 구성한다. 예) K_InsertMsg(O), K_ACTION_TYPE(O)

커서 변수 : 'c_' + Primary Identifier

커서변수의 경우에는 접두어 'c'를 사용한다. cursor parameter경우에는 접두어 'cp'를 사용한다. 예) c_Employees, c_ModelCode

레코드변수 : 'r_' + Primary Identifier

테이블이나 커서의 ROWTYPE 변수의 경우에는 접두어 'r을 사용한다. 로컬변수라도 v 접두어와 함께 사용하지 않는다. 예) r_employee

루프변수

루프변수는 일반적으로 i, j 같은 simple 변수명을 사용한다. 그러나 v_month 같이 상황에 따라 의미있는 변수를 사용할 수도 있다. 예) FOR v_month IN 1 .. 12 LOOP

Primary Identifier

주 식별자는 변수명의 구성요소 중 가장 중요한 부분으로 의미적으로 명확한 것을 사용한다. 대체로 컬럼명은 약어들로 구성되므로 Primary Identifier로 컬럼명을 사용하기 보다는 Full Name을 사용하는 것을 권고한다. 예) v_PrdMdlCd (X), v_prd_mdl_cd(△), v_ProductModelCode(O)

Object Naming Conventions

스키마 레벨의 오브젝트 테이블명, 컬럼명, 프로시저, 함수, 타입, 트리거 등의 Naming에 대한 가이드는 <Prefix><Primary Identifier><Suffix> 구조를 따른다. 테이블명과 컬럼명은 물리모델링 가이드를 따르며, 본 문서에서는 프로시저, 함수, 패키지, 타입명에 대한 규칙만을 정의한다. 데이터베이스 오브젝트명은 모두 대문자와 Underbar(_)로만 작성함을 원칙으로 한다.

함수명 : 'FN' + '_' + 함수 식별자

함수명은 'FN' 접두어를 사용한다. 예)FN_GET_ENG_NAME 단, 패키지내의 함수명은 FN 접두어를 사용하지 않아도 된다. 예) PKG_UTIL.GET_WORKING_DAY

프로시저 : 'SP' + '_' + 프로시저 식별자

프로시저명은 'SP' 접두어를 사용한다. 예) SP_SYS_LOG 단, 패키지내의 프로시저명은 FN 접두어를 사용하지 않아도 된다. 예) PKG_CODE.GET_CODE_LIST, PKG_COMMON.GET_LOCAL_TIME

패키지 : 'PKG' + '_' + 패키지 식별자

패키지명은 'PKG' 접두어를 사용한다. 예) PKG_DEPLOY 패키지 내의 함수, 프로시저 등의 오브젝트명은 접두어를 사용하지 않는 것을 원칙으로 한다. 예) PKG_COMMON.GET_SYS_TIME(O), PKG_COMMON.GET_USER_NAME(O)

타입 : 'T' + '_' + 타입 식별자

타입은 'T' 접두어를 사용한다. 예) T_VC_TAB

트리거 : 'TR' + '_' + 트리거 식별자<테이블명>

트리거명은 'TR' 접두어를 사용한다. 트리거가 트리거링 되는 조건에 관한 세부사항 (befor, after/Insert, Update, delete 등)은 트리거명에 넣지 않는다., 예) TR_SYS_USER

시퀀스 : 테이블명 + '_' + 'SEQ'

시퀀스 객체는 시퀀스 컬럼을 가진 테이블마다 하나씩 만드는 것을 원칙으로 하며, 접두어를 사용하지 않고, 'SEQ' 접미사를 사용한다. 예)USER_DEPT_SEQ

JOB : 'JOB' + '_' + Primary Identifier + ['_' + 스케줄정보]

JOB 객체나 Scheduled Job의 경우에는 'JOB' 접두어를 사용한다. 예) JOB_RSS 부가적으로 JOB 명에 배치주기 정보를 포함해도 무방하다.

표 2 Object Name Convention

Comments

주석은 유지보수 및 코드 설명을 위해 반드시 입력한다. 주석 입력단위는 DDL 이나 DML 스크립트를 파일로 작성할 때 파일레벨의 주석, 그리고 스키마의 OBJECT 레벨의 주석, 패키지내의 함수나 프로지저 등 서브 오브젝트, 그리고 프로그램 코드 중 필요한 부분에 주석을 작성한다.

주석문은 /* */ 를 사용하지 않고, -- 문을 사용하는 것을 원칙으로 한다.

파일레벨 / 스키마 OBJECT 레벨의 주석

파일레벨 이나 스키마 Object 레벨에서는 파일명이나 오브젝트 명 및 설명, 변경정보 등을 기술한다.

함수 / 프로시저 등의 OBJECT 레벨의 주석

함수는 프로시서등의 오브젝트는 위의 기본 주석에 파라미터 정보, 리턴값 정보를 추가로 입력한다.

 * 끝으로 SQL Style Guide & Code Convention에 대한 출력자료(PDF문서)가 필요하시면 Comment로 남겨주시면 메일로 보내드립니다. 너무 요청자가 많으면 파일을 업로드 해 드리도록 하겠습니다. ㅋㅋ 제 생각에는 별로 요청하시는 분 없을것 같거든요.

아래 내용은 제가 2008년 프로젝트 당시에 작성한 문서입니다. 당시, 자바나 닷넷은 Code Style Guide 혹은 Code Convention등의 문서가 많았지만, SQL 및 PL/SQL에 대한 문서는 거의 없어서 제가 작성했던 문서입니다. 블로그 만든 기념으로 그 때 문서를 공유합니다. 문서가 길어서 Style Guide 와 Naming Convention 편을 분리해서 작성했습니다. 실제 내용은 프로젝트 개발자를 위한 가이드라서 좀 딱딱한 문체로 기술되었습니다.

프로젝트 팀간의 Formatting 공유를 위해 제가 사용중인 Toad용 Formatting 파일을 함께 첨부합니다. 첨부파일은 Toad Version별로 커스터마이징 되어 있습니다. 자신의 버전에 맞는것을 다운 받아 덮어쓰시면 됩니다. 모, 직접 Toad Formatter를 하나하나 설정해서 사용하셔도 됩니다.

본  문서는 SQL 작성시 필요한 기본적인 Coding Style을 제공함으로써 SQL의 가독성을 높이고 유지보수 편의성을 제공하고자 한다.

Basic Layout

Tabs

기본적인 탭 사이즈는 4로 한다. 또한, 탭을 나타낼 때 Tab을 사용하지 않고 Space를 사용한다.

Margin

출력을 위해서는 80컬럼을 기본적으로 사용하나, SQL은 복잡한 Subquery 사용시 라인이 많이 늘어나므로 기본적으로 120 컬럼을 사용한다.

Indenting

기본적인 Indent 사이즈는 4로 Tab 사이즈와 동일하게 한다.

Case

SQL은 대문자를 사용하여 작성함을 원칙으로 한다. 아래에 특별히 언급하지 않은 모든 텍스트는 대문자(Uppercase)를 사용하여 작성한다.

Keywords

SQL의 모든 키워드 (예:SELECT, INSERT, BEGIN 등)는 모두 대문자(Uppercase)를 사용한다.

Built-ins / Built-in packages

DBMS에 내장된 함수 (DECODE, SUBSTR, NVL 등) 및 내장 패키지 (DBMS_OUTPUT, DBMS_SQL, UTL_FILE 등)는 모두 대문자(Uppercase)를 사용한다.

Table Name / Column Name

일반적으로 테이블 명 및 컬럼명, Alias 명, User 함수명 등은 소문자를 주로 사용하나 국내에서 테이블명 및 컬럼명이 약자를 주로 사용하므로 대문자가 가독성이 높아 모두 대문자(Uppercase)로 기술하는 것을 원칙으로 한다.

PL/SQL Variables

PL/SQL의 변수명은 예외적으로 대문자를 사용하지 않으며, 접두어 및 Camel 표기법을 사용한다. 상세한 내용은 Naming Rule 부분을 참조한다.

Lists and Operators

Variable Declarations

변수선언은 변수명과 변수타입명의 정렬방식은 세로줄라인을 맞추는 Fixed 방식을 사용한다.

Parameter Declarations

함수, 프로시저, 패키지 등의 PL/SQL에서의 파라미터 선언 스타일은 각 변수별로 한 라인씩 작성하는 Stacked 방식을 사용한다. 정렬방식은 각 변수별로 변수명, 타입등의 세로줄을 맞추는 Fixed 방식을 사용한다.

단, 파라미터 변수가 2~3개이어서 한 라인을 넘지 않는 경우에는 변수를 라인별로 작성하지 않고 한 라인에 기술할 수 있다.

Parameters

함수나 패키지등을 호출할 때 파라미터 변수를 입력하는 방식은 기본적으로는 Wrapped 방식 – 모든 파라미터 변수를 한줄에 입력하여 호출하도록 한다.

단, 파라미터로 입력하는 내용이 너무 길어질 경우 여러줄로 입력하여 한눈에 파악할 수 있도록 작성한다.

Named Parameters의 경우에는 여러줄로 나누어서 호출하는 것을 원칙으로 하며, 변수명과 인자값은 각 세로줄을 맞추는 Fixed 방식을 사용한다.

Parentheses

함수 호출시 괄호 및 스페이스 처리에 대한 규칙은 호출하는 인자들 간에만 공백을 주고, 함수명, 프로지서명과는 공백을 주지 않는다. 또한, 첫번째 변수와 마지막 변수와 괄호 사이에도 공백을 넣지 않는다.

Commas

컬럼리스트, 파라미터 리스트 등에서 ,(콤마)는 컬럼 앞에 둔다. 일반적으로 컬럼 뒤에 많이 기술하나 ,(콤마)를 앞쪽에 두면 콤마의 누락을 쉽게 파악 할 수 있다.

And – Or

Where 조건에서 AND, OR 연산자를 사용할 때 기본적으로 각 연산자를 기준으로 한라인씩 기술하는 Stacked 방식을 사용하여 기술한다.

또한, AND, OR가 동시에 사용되는 경우에는 OR 부분을 명확히 하기 위해서 ( )를 사용하여 표기한다. 그리고 연산자를 좌측에 두고 컬럼리스트가 좌측 정렬되도록 정렬한다.

Plus-Minus-Mul-Div-Conat

사칙연산 및 문자열 연결 연산자의 경우 연산자를 기준으로 여러줄로 작성하지 않고, 한 줄로 기술한다.

Specific Statements

:= Assignments

변수에 값을 할당할 때는 할당연산자(:=)를 기준으로 정렬한다.

SELECT / FETCH / EXECUTE

SELECT 문을 기술할 때 SELECT, INTO, FROM WHERE 등의 키워드는 우측 정렬을 원칙으로 한다.

SELECT문의 컬럼 리스트는 한줄에 하나의 컬럼을 기술하는 것을 원칙으로 한다. 단, SQL의 조회하고자 하는 컬럼의 개수가 적어 한 줄에 기술이 가능한 경우에는 한 줄에 써도 무방하다.

SELECT 컬럼 리스트와 동일하게 FROM, ORDER BY, GROUP BY RETURNING 리스트 도 한 줄에 하나의 컬럼을 기술하는 것을 원칙으로 한다. SELECT 문과 동일하게 해당절의 컬럼 개수가 적어 한 줄에 기술이 가능한 경우에는 한 줄에 써도 무방하다.

INSERT

INSERT문도 SELECT 문과 동일한 스타일을 따른다. 즉 INSERT문을 기술할 때 INSERT INTO, VALUES 등의 키워드는 우측 정렬을 원칙으로 한다.

INSERT 문의 컬럼이나 VALUES리스트는 SELECT문의 컬럼 리스트와 동일하게 한줄에 하나의 컬럼을 기술하는 것을 원칙으로 한다. 단, SQL의 조회하고자 하는 컬럼의 개수가 적어 한 줄에 기술이 가능한 경우에는 한 줄에 써도 무방하다.

UPDATE

UPDATE문도 SELECT 문과 동일한 스타일을 따른다. 즉 UPDATE문을 기술할 때 UPDATE, SET, WHERE 등의 키워드는 우측 정렬을 원칙으로 한다.

DELETE

DELETE문도 SELECT 문과 동일한 스타일을 따른다. 즉 DELETE문을 기술할 때 DELETE, WHERE 등의 키워드는 우측 정렬을 원칙으로 한다.

Table Alias

Join문에서 Table Alias를 부여할 때 일반적으로 A, B, C 순으로 작성하는 경우가 많다. 이것보다는 테이블을 파악하기가 용이한 의미있는 약어를 사용한다. 단, 약어는 3자를 넘기지 않는다. 1글자로 구분이 가능한 경우에는 한 글자로 사용한다.

예)
DEPT => D
MODEL_CATEGORY_INF => M OR MC
HISTORY => H

Toad Formatting

Use Formatting Tool

모든 개발자들이 공통적으로 위에서 정의한 SQL Style을 적용하기 위해서 Toad의 Formatting Tool을 사용한다. 다른 Tool들도 Formatting 기능을 제공하기는 하나, Toad가 포맷팅 기능은 가장 강력하다. 그러므로 개발자들이 다른 툴을 주로 사용하더라도 최종 SQL문에 대해서는 Toad의 포맷팅 기능을 사용하여 SQL 스타일을 맞추면 된다.

Formatting Setup

본 문서와 함께 제공되는 FmtPlus.opt 파일을 PC의 동일파일의 경로에 덮어쓴다.
예) C:\Users\Administrator\AppData\Roaming\Quest Software\Toad for Oracle\10.5\User Files\FmtPlus.opt에 존재함. 개인 개발자들의 정확한 위치는 Toad > View > Formatting Options 메뉴를 실행하면 열린 Formatter Window의 타이틀에 전체 경로가 나타난다. 그 부분을 참고하면 된다.

FmtPlus_toad_v10.x.zip

FmtPlus_toad_v9.5_9.6.zip

FmtPlus_toad_v9.7.zip

프로젝트 수행시 프로젝트에 맞는Formatting 옵션을 설정하고자 한다면, Toad Formatter에서 프로젝트에 적합하도록 수정한 후 해당 파일을 개발자에게 공유해서 동일한 포맷팅을 사용하도록 하면 된다.

그림 1 Toad Formatter 실행 화면

Toad에서 Formatting하기

아래 그림과 같이 Formatting을 하고자 하는 블록을 선택한 후 툴바를 클릭하면 SQL이 포맷팅 된다.
Edit > Format Code 를 선택해도 동일하다. 단축키는 Shift + Ctrl + F 이다.

그림 2 Formatting 이전 SQL

그림 3 Formatting 실행 이후

Exceptions

Toad로 대부분 필요한 수준의 Formatting이 되어지긴 하나, 일부 SQL에 대해서는 Formatting 한 결과가 오히려 한눈에 파악하기가 어려운 경우도 있으며, Toad v9.x에서는 MERGE 문 같은 경우는 제대로 처리조차 못하고 있다. 이런 경우에는 일반적인 관습을 따라서 개발자가 한눈에 파악하기 좋게 SQL을 작성하도록 한다.

Connect By 구문 작성시

CONNECT BY 구문 작성시 키워드의 글자 길이가 길어서 Formatting 툴을 사용하면 키워드를 기준으로 우측정렬 하는 현재 스타일에서 오히려 보기에 안 좋을 수도 있다. 이 경우에는 예외적으로 CONNECT BY의 Full Keyword를 기준으로 정렬을 해도 되고, CONNECT 키워드만을 기준으로 정렬을 해도 무방하다.

MERGE 문 등의 예외 처리

Merge문 작성시 Toad v.9.x버전에서는 Formatting 툴을 이용하면 WHEN MATCHED THEN 구문 이후 UPDATE 문에 대해 기본적인 UPDATE 문에서 정한 Style이 적용되지 않는다. WHN NOT MATCHED THEN 이후의 INSERT 문도 마찬가지다. Toad v.10.x 에서는 제대로 포맷팅 된다.

이처럼 오라클의 버전업에 따른 신규 기능의 경우, 제대로 포맷팅이 안될 경우에는 Formatting 툴을 이용하지 않고 보기 좋게 스타일 가이드에 맞게 작성한다.