Java Programming Style Guidelines
출처:http://www.wgshim.com/JavaCodingStandard/index.cgi?answer=%B8%ED%B8%ED%20%B0%FC%B7%CA(Naming%20Conventions)#q7
원문: Java Programming Style Guidelines
출처:http://www.wgshim.com/JavaCodingStandard/index.cgi?answer=%B8%ED%B8%ED%20%B0%FC%B7%CA(Naming%20Conventions)#q7
원문: Java Programming Style Guidelines
명명 관례(Naming Conventions)
#2. 패키지를 표현하는 이름은 모두 소문자를 사용함.
| 2. 패키지를 표현하는 이름은 모두 소문자를 사용한다. |
| mypackage, com.company.application.ui |
| 이 패키지 명명 관례는 Java 핵심 패키지들의 명명에 Sun 社 가 사용하고 있는 것입니다. 패키지 이름의 시작부는 반드시 도메인 이름으로 소문자를 사용해야만 합니다. |
#3. 타입을 표현하는 이름은 대소문자를 혼용할 수 있지만, 반드시 명사를 사용하고 시작 글자를 대문자로 지정함.
| 3. 타입을 표현하는 이름은 대소문자를 혼용할 수 있지만, 반드시 명사를 사용하고 시작 글자를 대문자로 지정한다. |
| Account, EventHandler |
| Java 개발자 커뮤니티에서 사용하는 일반적인 관습이며, Sun 社 가 Java 핵심 패키지들의 타입 명명에 사용하고 있는 것입니다. |
#4. 변수의 이름은 대소문자를 혼용할 수 있지만 반드시 소문자로 시작함.
| 4. 변수의 이름은 대소문자를 혼용할 수 있지만 반드시 소문자로 시작한다. |
| account, eventHandler |
| Java 개발자 커뮤니티에서 사용하는 일반적인 관습이며, Sun 社 가 Java 핵심 패키지들의 변수이름 명명에 사용하고 있는 것입니다. 변수와 타입을 손쉽게 구별할 수 있도록 하면, 이름의 충돌이 발생하는 것을 효과적으로 해결할 수 있게 됩니다. 예) Account account; // 선언문 |
#5. 상수(final 변수)의 이름은 반드시 모두 대문자로 지정하고 '_' 를 사용하여 단어들을 구분함.
| 5. 상수(final 변수)를 표현하는 이름은 반드시 모두 대문자로 지정하되 '_' 를 사용하여 단어들을 구분한다. |
| MAX_ITERATIONS, COLOR_RED |
| Java 개발자 커뮤니티에서 사용하는 일반적인 관습이며, Sun 社 가 Java 핵심 패키지에 사용하고 있는 것입니다.
일반적으로, 이러한 상수의 사용은 최소화해야만 합니다. 대다수의 경우 상수 변수를 메소드로 구현하는 것이 더 낫습니다: int getMaxIterations() // NOT: MAX_ITERATIONS = 25 이러한 양식이 보다 읽기에 편하며, 클래스의 값을 참조하는 일관된 인터페이스를 제공할 수 있다는 장점을 가집니다. |
#6. 메소드의 이름은 대소문자를 혼용할 수 있지만 반드시 동사를 사용하며 소문자로 시작함.
| 6. 메소드의 이름은 대소문자를 혼용할 수 있지만 반드시 동사를 사용하며 소문자로 시작한다. |
| getName(), computeTotalWidth() |
| Java 개발자 커뮤니티에서 사용하는 일반적인 관습이며, Sun 社 가 Java 핵심 패키지에 사용하고 있는 것입니다. 이 방식은 변수의 이름을 지을 때 사용하는 관례와 동일합니다. 하지만, Java 에서는 이미 특별한 양식(getter/setter, 동사로 시작하는 이름, JVM Spec, 등)에 의거하여 메소드는 변수를 구분합니다. |
#7. 축약형(Abbreviation) 과 두문자어형(頭文字語: Acronym) 을 이름에 사용할 경우...
| 7. 축약형(Abbreviation) 과 두문자어형(頭文字語: Acronym) 을 이름에 사용할 경우에는 전부 대문자로 지정하지 않는다. |
| exportHtmlSource(); // exportHTMLSource(); 가 아님 openDvdPlayer(); // openDVDPlayer(); 가 아님 |
| 축약형 혹은 두문자어형 이름을 모두 대문자로 지정하게 되면 앞서 기술한 명명 지침들과 충돌이 발생하게 됩니다 (대표적으로 상수에 대한 명명 지침과 혼동될 수 있습니다). 그렇다고 이 유형의 이름을 dVD, hTML 등 과 같이 다양한 형태로 지정할 경우에는 가독성이 떨어집니다. 또 다른 문제점으로는 위의 예제에서 살펴볼 수 있는 바와 같이, 이 유형의 이름이 다른 이름과 결합되는 경우 가독성이 극도로 나빠진다는 것입니다. 후속하는 단어가 있을 경우는 더욱 각별히 주의해야 합니다. |
#8. private 접근 제한자를 갖는 클래스 변수에 '_' 접미사를 사용함.
| 8. private 접근 제한자를 갖는 클래스 변수에 '_' 접미사를 사용한다. |
| class Well { private int depth_; ... } |
| 변수의 이름이나 타입과는 별개로, 변수의 범위(scope)는 매우 중요한 특성입니다. 접미사 '_' 를 사용함으로써 클래스 범위의 변수(로컬 변수가 아닌)임을 쉽게 구별할 수 있게 됩니다. 클래스 변수는 메소드 내에서 선언되는 로컬 변수에 비해 중요도가 높기 때문에 프로그래머가 각별히 주의해야 합니다.
'_' 를 사용하는 명명 규칙은 부가적으로 setter 메소드에서의 이름 충돌문제를 깔끔하게 해결해 줍니다: void setDepth (int depth) 제기될 수 있는 이슈거리는 '_' 를 변수의 접두사로 쓸 것인가 접미사로 쓸 것인가에 대한 것입니다. 두 가지 모두 일반적으로 널리 사용되는 방법이기는 합니다만, 이름을 읽기 편하다는 측면에서 후자의 것을 권고합니다. 변수의 이름에 볌위를 식별할 수 있도록 하자는 제안은 한 동안 많은 논쟁을 불러일으켰습니다. 그런데 현재에는 이러한 방법이 수용되어 전문 개발자 커뮤니티에서도 일반적인 관례로 점차 정착이 되고 있는 것 같습니다. |
#9. 일반적인 변수의 이름은 타입의 이름과 동일하게 지정함.
| 9. 일반적인 변수의 이름은 타입의 이름과 동일하게 지정한다. |
| 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) 가 아님 |
| 용어나 이름의 수를 줄이는 것이 코드의 복잡도를 줄여줍니다. 또한 변수의 이름만으로도 그 타입을 손쉽게 유추할 수 있게 해준다는 장점도 있습니다.
만약 어떠한 이유에선가 이러한 관례가 맞지 않는 것처럼 느끼신다면, 이는 분명 타입이름 자체를 잘못 지정한 것입니다. 일반적이지 않은 변수들은 각기 나름의 역할(role)을 가지고 있습니다. 이러한 변수들은 역할과 변수의 타입을 결함하여 이름을 짓곤 합니다. Point startingPoint, centerPoint; |
#10. 모든 이름은 영어로 작성함.
| 10. 모든 이름은 영어로 작성한다. |
| fileName; // filNavn 나 파일이름 이 아님 |
| 국제적인 개발에 있어서 영어가 선호되기 때문입니다. |
#11. 넓은 범위에 영향을 미치는 변수는 긴 이름을 부여하고, 좁은 범위의 변수는 짧은 이름을 부여함.
| 11. 넓은 범위에 영향을 미치는 변수는 긴 이름을 부여하고, 좁은 범위의 변수는 짧은 이름을 부여한다 [1]. |
| 임시 저장공간이나 인덱스로 사용되는 Scratch variable (주: 의미있는 값을 갖지 않고 그때그때 상황에 따라 값들을 잠시 보관해 두기 위한 변수로, 대개 보유한 값이 얼마 후에 의미가 없어지거나 삭제됨)들은 매우 짧은 이름을 부여하십시요. 프로그래머가 그러한 변수들을 읽음과 동시에, 이 변수는 몇 라인 뒤에 그 값이 유효하지 않을 것임을 짐장할 수 있게 해야 합니다. 보편적인 scratch variable 로는 정수를 저장하는 i, j, k, m, n 가 있고 문자를 저장하는 c, d 가 있습니다. |
#12. 호출하려는 객체의 이름을 통해 의미를 짐작할 수 있다면, 메소드의 이름을 간략화할 수 있음.
| 12. 호출하려는 객체의 이름을 통해 의미를 짐작할 수 있다면, 메소드의 이름을 간략화할 수 있다. |
| line.getLength(); // line.getLineLength(); 가 아님 |
| 클래스 선언 시에는 후자의 것이 자연스럽지만, 사용할 때에는 위 예에서 볼 수 있듯이 중언부언하는 느낌을 줄 수 있습니다. |
#13. get/set 이라는 용어는 반드시 애트리뷰트에 직접 접근하는 메소드에 사용.
| 13. get/set 이라는 용어는 반드시 애트리뷰트에 직접 접근하는 메소드에 사용한다. |
| employee.getName(); matrix.getElement (2, 4); employee.setName (name); matrix.setElement (2, 4, value); |
| 이 접근 메소드 명명 관례는 Java 핵심 패키지들의 명명에 Sun 社 가 사용하고 있는 것입니다. 실제 자바빈즈를 작성할 때에는 이 명명규칙을 준수해야 합니다. |
#14. is 접두사를 불리언 변수와 메소드에 사용.
| 14. is 접두사를 불리언 변수와 메소드에 사용한다. |
| isSet, isVisible, isFinished, isFound, isOpen |
| 이 불리언 메소드와 변수에 대한 명명 관례는 Java 핵심 패키지들의 명명에 Sun 社 가 사용하고 있는 것입니다. 실제 자바빈즈를 작성할 때에는 이 명명규칙을 준수해야 합니다.
is 접두사를 사용함으로써 일반적으로 status 와 flag 와 같은 좋지 않은 불리언 이름을 선택하는 문제를 해결할 수 있습니다. isStatus 나 isFlag 는 간결하지만 프로그래머에게 의미를 풍부하게 전달할 수 없다는 점에서 바람직하지 못합니다. 일부 상황에서는 is 접두사가 아닌 보다 더 적합한 접두사를 사용할 수도 있습니다. has, can, should 접두사들을 그런 대안으로 활용하실 수 있을 것입니다: boolean hasLicense(); |
#15. compute 라는 용어는 무엇인가를 계산(시간이 소요되는)하는 메소드에 사용가능.
| 15. compute 라는 용어는 무엇인가를 계산(시간이 소요되는)하는 메소드에 사용할 수 있다. |
| valueSet.computeAverage(); matrix.computeInverse() |
| 프로그래머로 하여금 보는 즉시 이 메소드는 잠재적으로 시간이 소요되는 작업을 수행하고 있다는 것을 주지심으로써, 이 메소드의 결과를 반복해서 사용하고자 할 경우에 프로그래머는 계산된 값을 캐시해 둘 것을 고려하게 만들 수 있습니다. 용어를 일관성있게 사용하는 것은 가독성을 높이는 지름길입니다. |
#16. find 라는 용어는 무엇인가를 찾는 메소드에 사용가능.
| 16. find 라는 용어는 무엇인가를 찾는 메소드에 사용할 수 있다. |
| vertex.findNearestVertex(); matrix.findMinElement(); |
| 프로그래머로 하여금 보는 즉시 이 메소드는 최소한의 계산을 통해 요청하는 결과를 찾을 수 있는 메소드라는 것을 알려주십시오. 용어를 일관성있게 사용하는 것은 가독성을 높이는 지름길입니다. |
#17. initialize 라는 용어는 객체나 개념이 확립되어지는 곳에 사용가능.
| 17. initialize 라는 용어는 객체나 개념이 확립되어지는 곳에 사용할 수 있다. |
| printer.initializeFontSet(); |
| 미국식 initialize 가 영국식 initialise 보다 바람직합니다. init 라는 축약형 이름은 절대로 사용하지 마십시오. |
#18. JFC (Java Swing) 변수들은 각 컴포넌트의 타입을 접두사로 사용함.
| 18. JFC (Java Swing) 변수들은 각 컴포넌트의 타입을 접두사로 사용한다. |
| widthScale, nameTextField, leftScrollbar, mainPanel, fileToggle, minLabel, printerDialog |
| 변수의 이름 자체가 자신이 어떤 타입의 변수인지 알려주기 때문에 객체가 어떤 자원인지 쉽게 알 수 있습니다. |
#19. 컬렉션의 이름은 반드시 복수형으로 사용함.
| 19. 컬렉션의 이름은 반드시 복수형으로 사용한다. |
| vertex (one vertex), vertices(a collection of vertices) account (one account), accounts(a collection of accounts) |
| 여기서의 컬렉션은 java.util.Collection 변수와 단순 배열과 같은 Collection 의 자손들을 의미합니다. |
#20. n 접두사는 객체의 개수를 나타내는 변수에 사용함.
| 20. n 접두사는 객체의 개수를 나타내는 변수에 사용한다. |
| nPoints, nLines |
| 이 표기법은 개체의 개수를 나타내는 수식의 표기법에서 차용한 것입니다.
Sun 社 는 Java 핵심 패키지에서 이런 용도로 num 접두사를 사용한다는 것에 주목해 보겠습니다. 이는 필경 number of 에 대한 축약어를 의미할 것입니다만, 그 보다는 number 를 연상시킴으로써 변수 이름을 이상하게 만들거나 혼동을 불러일으킬 수 있습니다. 만약 "number of" 를 더 선호하신다면, n 대신에 numberOf 접두사를 사용하실 수도 있을겁니다. num 접두사는 사용하시지 않기를 강력하게 권합니다. |
#21. No 접미사는 엔터티 번호를 나타내는 변수에 사용함.
| 21. No 접미사는 엔터티 번호를 나타내는 변수에 사용한다. |
| tableNo, employeeNo |
| 이 표기법은 엔터티의 번호를 나타내는 수식의 표기법에서 차용한 것입니다.
또 다른 우아한 표기 방법으로는 i 을 접두사로 사용하는 것입니다: iTable, iEmployee. 이 방법은 효과적으로 변수에 iterator 로의 역할을 부여하게 됩니다. |
#22. Iterator 변수들은 i, j, k 등 과 같은 이름을 사용함.
| 22. Iterator 변수들은 i, j, k 등 과 같은 이름을 사용한다. |
| while (Iterator i = pointList.iterator(); i.hasNext(); ) { : } for (int i = 0; i < nTables; i++) { : } |
| 이 표기법은 iterator 를 나타내는 수식의 표기법에서 차용한 것입니다.
j, k 등과 같은 이름의 변수들은 중첩된 반복문 내에서만 사용합니다. |
#23. 대응하는 단어가 있는 이름은 반드시 함께 사용함.
| 23. 대응하는 단어가 있는 이름은 반드시 함께 사용한다 [1]. |
| 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 |
| 대칭을 이루도록 함으로써 복잡도를 줄일 수 있습니다. |
#24. 축약형 이름의 사용은 피함.
| 24. 축약형 이름의 사용은 피한다. |
| computeAverage(); // compAvg(); 가 아님 |
| 고려해 볼 두 종류의 단어들이 있습니다. 먼저 프로그래밍 언어를 구사하는 데에 있어 빈번하게 사용되는 일반적인 단어들이 있습니다. 이들 단어는 절대로 축약형을 사용하지 말아야 합니다:
command 대신 cmd 그 다음, 도메인에서 사용하는 특수한 두문자어나 축약어들은 축약형을 그대로 사용합니다. 이들 구문은 굳이 풀어 나열하지 않고 축약형을 사용하십시오. 다음과 같이 사용하시면 안됩니다: html 대신 HypertextMarkupLanguage |
#25. 불리언 변수 이름은 절대로 부정적인(거짓인) 이름을 사용하지 않음.
| 25. 불리언 변수 이름은 절대로 부정적인(거짓인) 이름을 사용하지 않는다. |
| boolean isError; // isNotError 가 아님 boolean isFound; // isNotFound 가 아님 |
| 문제는 불리언 변수에 부정적인 이름을 사용할 경우, not 연산자를 사용할 경우 부정의 부정을 계산해야 하는 혼동을 초래한다는 것입니다. 예를 들어, !isNotError 에서 처럼, 신속하게 이것이 무엇을 의미하는지 인지할 수 없게 됩니다. |
#26. 관련있는 상수(final 변수)들은 공통 타입의 이름을 접두사로 사용하여 그룹핑함.
| 26. 관련있는 상수(final 변수)들은 공통 타입의 이름을 접두사로 사용하여 그룹핑한다. |
| final int COLOR_RED = 1; final int COLOR_GREEN = 2; final int COLOR_BLUE = 3; final int MOOD_HAPPY = 1; final int MOOD_BLUE = 2; |
| 이 표기방법은 상수들이 어디에 속해있는지 상수가 무엇을 나타내고 있는지 식별하는데 도움이 됩니다. |
#27. 예외(Exception) 클래스들은 Exception 이라는 접미사를 사용함.
| 27. 예외(Exception) 클래스들은 Exception 이라는 접미사를 사용한다. |
| class AccessException { : } |
| 사실 예외 클래스들은 프로그램의 핵심 디자인에 해당되지 않기 때문에, 이와 같은 방식으로 이름을 지정함으로써 상대적으로 클래스들 중에서 눈에 띄게(구분을 용이하게) 해두는 것이 좋습니다. 이 명명 관례는 Java 기본 라이브러리들에 Sun 社 가 사용하고 있는 표준입니다. |
#28. 디폴트 인터페이스 구현은 Default 라는 접두사 사용가능.
| 28. 디폴트 인터페이스 구현은 Default 라는 접두사를 사용할 수 있다. |
| class DefaultTableCellRenderer implements TableCellRenderer { : } |
| 이 방법은 인터페이스 메소드들에 대한 디폴트 처리작업을 제공하는 구현물에, 간단하게 이름을 부여하는 방법으로 널리 사용되고 있는 방법입니다. Default 접두사를 클래스의 이름에 부여하는 이 명명 관례는, Java 기본 라이브러리들에 Sun 社 가 채택한 방식입니다. |
#29. 함수(객체/결과를 리턴하는 메소드)의 이름은 '처리 후 무엇을 리턴하는지'를 의미하고, 프로시저(void 메소드)의 이름은 '무엇을 처리하는지'를 의미함.
| 29. 함수(객체/결과를 리턴하는 메소드)의 이름은 '처리 후 무엇을 리턴하는지'를 의미하고, 프로시저(void 메소드)의 이름은 '무엇을 처리하는지'를 의미한다. |
| 메소드가 무엇을 하는지. 의도하지 않는 것들이 무엇인지를 명확하게 해주기 때문에, 가독성을 높여줍니다. 또한 이 방법은 예기치 못한 부작용(side effect)들로부터 코드를 명쾌하게 유지시켜 줄 수 있습니다. |
