개발 표준 정의서/명명 규칙

개발표준정의.txt

1. 목자
 
개요
명명규칙 표준
Jsp, servlet 개발표준
Batch 프로그램 개발표준
Directory 표준
 
 
2. 개요
프로젝트의  개발 시 개발생산성 향상 및 운영의 효율화를 위해 반드시 준수되어야 하는 준수사항을 정의함
 
1) 제시된 표준은 철저히 준수한다.

2) 새로운 정의가 추가로 필요한 경우는 본 자료를 작성한 담당자와 협의하여 해당 내용을 정의하고, 본 표준서에 수록한 후
    프로젝트팀 전체에 공지한다.
 
3) 모든 화면은 최대 응답속도 5초 이내를 목표로 Design 되어야 한다.

4) 표준을 준수하지 못할 경우에는 PM 및 인수책임자의 허가를 받아야 하며, 그럴 경우에도 해당 시스템 내에는 일정한
    표준을 정의하여 적용시켜야 한다.(품질계획서 기준을 따른다)
 
5) 본 표준안은 최소한의 필수사항을 지키도록 유도하고 해서는 안되는 것들을 지적하는 내용이며, 개개인의 다양한 능력과
    개념들로 본 표준을 확장시켜 시스템에 적용시키도록 한다.
 
 
 
3. 명명규칙 표준
시스템을 개발하는데 있어 표준 Naming Rule을 적용하여 개발자 및 운영자가 분석 및 코딩하는데 있어 좀더 쉽게 접근할 수 있도록 표준 Naming Rule을 적용한다.
 
1) 시스템 개발코드
시스템 영역별 코드를 분류한다. ex) ~ 시스템 -> portalSystem
 
2) Package, Java class, Java archive 명명 규칙
모든 Java class는 영문 대소문자를 혼용할 수 있지만, 반드시 명사를 사용하고 시작 글자를 대문자로 지정하며 camel case에
준하여 작성한다.
Ex) StringUtil.java, PortalBeansFactory.java
 기능명이 postfix에 포함될 수 있으면 포함시킨다.

1) Data Access Object(DAO)
2) 인터페이스(IF)
3) Batch(Bat)
4) 유틸리티(Util)
5) 공통(Comm)
6) 로직자바빈즈(Beans)
...
ex) LoginDao.java
 
3) 변수명, 메소드명 명명 규칙
- 변수의 이름은 대소문자를 혼용할 수 있지만 반드시 소문자로 시작한다.
ex)  account, eventHandler

- 상수(final 변수)를 표현하는 이름은 반드시 모두 대문자로 지정하되 '_' 를 사용하여 단어들을 구분한다.
 ex)  MAX_ITERATIONS, COLOR_RED
 
- 메소드의 이름은 대소문자를 혼용할 수 있지만 반드시 동사를 사용하며 소문자로 시작한다.
ex) getName(), computeTotalWidth()
 
- 축약형(Abbreviation) 과 두문자어형(頭文字語: Acronym)을 이름에 사용할 경우에는 전부 대문자로 지정하지 않는다.
ex)
exportHtmlSource(); // exportHTMLSource(); 가 아님 
openDvdPlayer(); // openDVDPlayer(); 가 아님

- 일반적인 변수의 이름은 타입의 이름과 동일하게 지정한다.
ex)
void setTopic (Topic topic) // void setTopic (Topic value) 이 아님
   // void setTopic (Topic aTopic) 이 아님
   // void setTopic (Topic x) 이 아님
void connect (Database database)  // void connect (Database db) 가 아님
    // void connect (Database oracleDB) 가 아님
 
- 모든 이름은 영어로 작성한다.
 
- 넓은 범위에 영향을 미치는 변수는 긴 이름을 부여하고, 좁은 범위의 변수는 짧은 이름을 부여한다.
임시 저장공간이나 인덱스로 사용되는 Scratch variable(loop문내에서의 i, j, k 등과 같은)들은 매우 짧은 이름을 부여하도록
한다.
프로그래머가 그러한 변수들을 읽음과 동시에, 이 변수는 몇 라인 뒤에 그 값이 유효하지 않을 것임을 짐작할 수 있게 해야 한다.
 
- 호출하려는 객체의 이름을 통해 의미를 짐작할 수 있다면, 메소드의 이름을 간략화할 수 있다.
ex) line.getLength(); // line.getLineLength(); 가 아님
 
- get/set 이라는 용어는 반드시 애트리뷰트에 직접 접근하는 메소드에 사용한다.
ex)
employee.getName();
matrix.getElement(2, 4);
employee.setName(name);
matrix.setElement(2, 4, value);
 
-  is 접두사를 불리언 변수와 메소드에 사용한다.
ex) isSet, isVisible, isFinished, isFound, isOpen
이 불리언 메소드와 변수에 대한 명명 관례는 Java 핵심 패키지들의 명명에 Sun 社 가 사용하고 있는 것입니다.
실제 자바빈즈를 작성할 때에는 이 명명규칙을 준수해야 합니다.

is 접두사를 사용함으로써 일반적으로 status 와 flag 와 같은 좋지 않은 불리언 이름을 선택하는 문제를 해결할 수 있습니다. isStatus 나 isFlag 는 간결하지만 프로그래머에게 의미를 풍부하게 전달할 수 없다는 점에서 바람직하지 못합니다. 일부 상황에서는 is 접두사가 아닌 보다 더 적합한 접두사를 사용할 수도 있습니다.
has, can, should 접두사들을 그런 대안으로 활용하실 수 있을 것입니다.
ex)
boolean hasLicense();
boolean canEvaluate(); 
boolean shouldAbort = false;
 
- compute 라는 용어는 무엇인가를 계산(시간이 소요되는)하는 메소드에 사용할 수 있다.
ex)
valueSet.computeAverage();
matrix.computeInverse();
 
- find 라는 용어는 무엇인가를 찾는 메소드에 사용할 수 있다.
ex)
vertex.findNearestVertex(); 
matrix.findMinElement();
dao.findList();
 
 
- initialize 라는 용어는 객체나 개념이 확립되어지는 곳에 사용할 수 있다.
ex) printer.initializeFontSet();
 JFC (Java Swing) 변수들은 각 컴포넌트의 타입을 접미사로 사용한다.
ex)
widthScale, nameTextField, leftScrollbar, mainPanel, fileToggle, minLabel, printerDialog

 
- 컬렉션의 이름은 반드시 복수형으로 사용한다.
여기서의 컬렉션은 java.util.Collection 변수와 단순 배열과 같은 Collection의 자손들을 의미합
니다.
 n 접두사는 객체의 개수를 나타내는 변수에 사용한다.
ex) nPoints, nLines
 No 접미사는 엔터티 번호를 나타내는 변수에 사용한다.
ex) tableNo, employeeNo
 Iterator 변수들은 i, j, k 등 과 같은 이름을 사용한다.
ex)
while (Iterator i = pointList.iterator(); i.hasNext();) {
    ;
}
for (int i = 0; i < nTables; i++) {
    ;
}
 
 
- 대응하는 단어가 있는 이름은 반드시 함께 사용한다.
ex)
get/set, add/remove, create/destroy, start/stop, insert/delete, increment/decrement, old/new, begin/end, 
first/last, up/down, min/max, next/previous, old/new, open/close, show/hide ...
 
- 축약형 이름의 사용은 피한다.
ex) computeAverage(); // compAvg(); 가 아님
고려해 볼 두 종류의 단어들이 있습니다.
먼저 프로그래밍 언어를 구사하는 데에 있어 빈번하게 사용되는 일반적인 단어들이 있습니다. 
이들 단어는 절대로 축약형을 사용하지 말아야 합니다.
command 대신 cmd
copy 대신 cp
point 대신 pt
compute 대신 comp
initialize 대신 init 등등,
그 다음, 도메인에서 사용하는 특수한 두문자어나 축약어들은 축약형을 그대로 사용합니다.
이들 구문은 굳이 풀어 나열하지 않고 축약형을 사용하십시오. 다음과 같이 사용하시면 안됩
니다.
html 대신 HypertextMarkupLanguage
cpu  대신 CentralProcessingUnit
등등.
 
 
- 불리언 변수 이름은 절대로 부정적인(거짓인) 이름을 사용하지 않는다.
ex)
boolean isError; // isNotError 가 아님
boolean isFound; // isNotFound 가 아님
 관련있는 상수(final 변수)들은 공통 타입의 이름을 접두사로 사용하여 그룹핑한다.
ex)
final int COLOR_RED   = 1;
final int COLOR_GREEN = 2;
final int COLOR_BLUE  = 3;
 예외(Exception) 클래스들은 Exception 이라는 접미사를 사용한다.
ex) DataAccessException
 디폴트 인터페이스 구현은 Default 라는 접두사를 사용할 수 있다.
ex)
class DefaultTableCellRenderer implements TableCellRenderer {
    ...
}
 
 
4) Package, Java class, Jar
 
- Package : 사업이름.업무대분류 .중분류
 
-> Package이름은 소문자로 생성한다.

-> Source 부분 -> package  pos.업무대분류.중분류.기능구분;

-> 중분류 : 업무중분류 혹은 소분류에 적합한 이름을 명명한다.
 
            예) pos.ptl.login.action (action package)

pos.ptl.login.dao (dao package) 
pos.ptl.login.beans (beans package)
pos.ptl.login.bat  (batch package)
 
 
 
 
 
- Java class : 프로그램목록에 정의된 클래스 이름.java

-> 프로그램목록상의 클래스 이름에는 아래의 기능명이 postpix에 포함되어 있어야 한다.
  기능명  :  
 
① ACTION(Action)
② DAO(Dao)
    인터페이스(IF)
    Batch(Bat)
    유틸리티(Util)
    공통(Comm)
    빈스(로직-Beans)
    예) LoginAction.java (action)
                  LoginDao.java (dao)
 
 
 
- Jar : 업무대분류+기능별이름
 
-> 기능별이름 : 해당Jar성격에 맞는 이름 부여
예) PTLPortalDeploy.jar
 
 
 
 
 
5) 프레임워크 적용 시 설정파일 명명규칙
 
설정파일명.xml내의 클래스명과 별명 매핑규칙은 각 class 의 이름을 따르고 구분자를 통한 접근을 구분한다.
예) LoginAction.java  -  LoginAction
        구분자 : 키워드 – cmd, 매핑구분값 - view

 
6) 기타 Resource 명명규칙
 
- Html
 Html은 주로 공통적으로 사용하는 경우에 생성되고, 프로그램별로 생성되는 경우는 없다.

 고유코드 + “html설명 형태”로 이름을 만든다.
 “고유코드”는 대문자로 하고 “html 설명”은 첫 자는 대문자로 하고 대소를 구분하여 의미를 가지는 명칭으로 한다.
 확장자는 .html로 정하기로 한다.(.htm불가)
예) “PM” + “CalcPayment” + “.thml”
 Tag를 사용할 때 Tag명과 Attribute는 대문자로 사용한다.
 
 

- Javascript
 Java Script function명은 연관 업무와 기능을 위주로 명명한다.
 js 파일 : 유사한 성격을 가지는 함수들을 묶어 만든다.
 함수들이 가지는 “유사한 성격”을 표시할 수 있는 이름으로 대소를 구분하여 만든다.
 Javascript 함수의 이름은 class에서의 함수명칭과 동일한 원칙으로 작성한다.
 동일한 역할을 하는 함수이지만 jsp별로 구체적인 구현 내용이 틀린 경우 함수의 명칭과 인자를 통일 시킨다.(예를 들어 function validate());
 Js 파일의 경우 동일한 폴더에서 관리한다.
 
 
 
 
- Css
 css 파일의 경우 동일한 폴더에서 관리한다.
 구체적인 명명 규칙은 design을 할 수 있는 단계에서 다시 고려.
 
 
 
- Image
 이미지 파일은 사용 가능한 확장자를 제한하며(gif, jpg) 가능한 한 gif를 사용하도록 한다.
 확장자는 소문자를 사용하며, 명칭은 대소를 구분한다.
 모든 페이지에서 공통적으로 사용하는 바탕화면의 경우 “bgImage” + position + 순번 의 형태를 가진다.
 프로그램에서 공통적으로 사용하는 icon의 경우 icon의 역할을 기반으로 “icon” + role형태로 이름을 작성한다.(예를 들어 “iconZipNoDV.gif”, “iconSave.gif”)
 이미지의 경우 images 폴더 밑에 이미지의 성격별로 subfolder를 관리한다. 즉 바탕화면을 하나의 폴더에서 관리하고, 사원이미지를 또 다른 폴더에서 관리한다.
 “품목이미지” 처럼 데이터의 성격을 가지는 이미지의 경우 해당 table의 main key들의 조합을 이름으로 한다. (예를 들어 품목 이미지의 경우 ”사업장코드+ 품목아이디.gif,”, 사원이미지의 경우 “사원번호.gif” 형태를 가진다.
 
 
7) 주석처리
- 주석 부여 규칙

 프로그램의 이해를 도와 향후 유지보수가 용이하게 한다.
 전체적인 프로그램 설명은 프로그램 앞부분에 위치시킨다.
 각 Method 앞에 Method의 Parameter, Return Value의 의미와 Method의 간략한 설명을 기술한다.
 수정 시 수정 내역을 기술하여 수정 History를 기록한다.
 해당 프로그램의 핵심적인 중요Logic에 대해서는 반드시 그에 따른 주석을 추가한다.
 JavaDoc을 이용하여 프로그램 사양서를 작성할 수 있도록 한다.
 JavaDoc의 표준을 준수한다.

 JavaDoc에 의해 처리될 주석은 /**으로 시작해 */으로 종결된다. 각 라인마다 /* 으로 시작한다.

 사양서에 기술할 필요가 없는 주석은 자유롭게 기술한다.(/* */,//사용)
 
 
 
- 수정 이력 관리

 개발기간 중 Servlet, JSP등의 소스에 작성자 이외의 개발자가 소스를 수정하거나 Method를 추가할 경우 반드시 수정 내역을
  
    남기고 작성자에게 통보한다.
 
 
 
 
 
- 주석 방식 
    다음의 주석은 프로그램 가독성을 해치지 않은 범위내에서 한줄 코멘드(//)로 의미 설명함

 SQL COMMENT : SQL 문의 WHERE 절에 각 조건의 의미를 설명
 CONTROL COMMENT : 소스내의 모든 if, while등과 같은 분기가 있을 경우 그 직전라인에 분기 조건의 내용을 설명함
 변수 COMMENT : 활용 목적을 명시함
 
 
 
 
- 작성 항목

 클래스시작부에 아래 항목을 기술하고 필요항목을 추가하여 사용할 수 있다. 설명은 최대한 상세하게 기술한다. 
파일명
작성일자
작성자 (@author 홍길동)
참조 Class File (@see File DocSampleRef.java) 
설명
수정일자
수정자
수정내역
 
 
예) 
 /** 
   * Version : 1.0
  * 파일명: LoginAction.java
  * 작성일자 : 2007-12-24
* 작성자 : 홍길동
  * @see File CacheService.java
  * 설명 : 포털 로그인 화면
  * 수정일자 :  2007-12-25
  * 수정자 : 이남현
  * 수정내역 : getUserName() 메소드 추가.
*/
 
 
 
- 클래스 Method의 시작부에 아래 항목을 기술하고 필요항목을 추가하여 사용할 수 있다. 설명은 Method의 기능을 간략히 기술한다.

① 설명
② Argument (@param userID 사용자ID)
③ Return (@return 사용자명)
④ 예외처리 (@throws SampleException)
 
예)
 /**
  * 설명 : 이미 접속한 사용자인지 확인한다.
  * @param userID 사용자아이디
  * @return boolean 불린
* @throws NullPointException 세션객체가 Null일 때 발생
*/
 
8) 자바스크립트

공통으로 다수의 JSP에서 쓰이는 자바스크립트들은 관련된 기능에 따라 하나로 묶어 의미있는 이름을 부여한 파일로 관리한다.
 
이것을 JSP나 HTML에서 include하여 사용한다.

 
예) DateCommon.js, EventCommon.js
 
개발자 개별적으로 사용하거나 소수의 화면에서만 쓰이는 자바스크립트는 해당 소스코드를 <head>와 </head> 사이의
 
웹페이지 내에 유지한다.
 
 
 
 
9) Web 에서의 File 처리
 
 구분	기능 	 	 
 유형1	 File Upload	 이미지 등 바이너리파일 내용을 확인하지 않고 첨부형대로 서버로 전송함	 문서 파일
 유형2	 조회한 내용 File로 저장	 웹브라우져로 조회된 내용을 사용자 PC에 File로 저장함	 운용지시내역, 매매자료 file저장
 유형3	 File Download	 내용조회 없이 바로 File로 PC에 저장함	 
 
10) 기타
오류 메시지 처리 표준
오류 메시지는 공통 오류 메시지 화면에서 오류코드와 오류메세지를 같이 DISPLAY 하고 다시돌아가기 기능을 제공한다.