ANMIAN

파일 헤더를 제공하라
사소하지만 꽤 중요하다. 난 지금까지 제대로 지키지 않았다. 앞으로는 잘 하도록 노력해야겠다. 대부분의 회사에서는 법률적인 이유로 모든 소스 파일에 가시적인 저작권 공지를 포함시키도록 의무화하고 있단다.
/*************************************
* 파일 : FileName.java
* 목적 :
* 알림 : 저작권표시
*************************************/

에러를 적절하게핸들링하라
에러는 발생한 곳과 가까운 곳에서 처리하는 것이 좋다. 에러가 발생하면 어디서 왔는지, 에러의 이유가 무엇인지, 에러가 발생한 것은 무엇을 의미하는 것인지 알기 쉽도록 해라.(어떻게? 잘~)

의미 있는 코멘트를 작성하라
학교에서 처음 프로그래밍을 배우면서 코드를 작성하고 발표수업이 있을 때 모든 문장에 코멘트를 달도록 강요받은 기억이 있다. 코멘트가 너무 많은 코드는 오히려 보기 불편하다. 가능하면 코멘트가 필요없도록 작성하되 그러고도 남아있는 부분에 대해서는 적절한 분량의 코멘트를 추가해야 한다.
* 파일헤더, 함수의 설명, 변수에 대한 설명은 가능하면 생략하지 마라.


문서화의 여러가지 방법

문학적 프로그래밍(프로그램을 작성하지 말고, 문서를 작성하라. 소설처럼 써라.)
장점
* 문학적 프로그래밍은 문서작성에 강점을 둔다.
* 문서가 가까이 있으므로 업데이트할 때 문서도 함께 업데이트 하기 쉽다.
* 전체 코드베이스에 대해 단 하나의 문서만 존재한다는 사실이 보장된다.(코드 자체가 문서기 때문)
* 일반적으로 코멘트에 쓰이지 않는 항목도 문서화하도록 유도한다.(사용된 알고리즘에 대한 설명, 코드가 올바르다는 증명, 그렇게 설계하게 된 결정의 정당성.)
* 유지보수에서 빛이 난다.
단점
* 코드가 아니라 문서 전체를 작성해야 하므로 대부분의 프로그래머들이 힘들고 귀찮아 한다.
* 또 하나의 컴파일 단계가 필요하고, 그것이 작업 속도를 느리게 만든다.(아직 바로 컴파일해줄만한 툴은 없단다. 당연하지!)
* 정말 문서화가 필요하지 않은 부분까지도 문서화하게 될지도 모른다. 또는 일부를 문서화하지 않게 될지도 모른다. 귀찮으면 아예 하지 않는 것이 좋다. 이도저도 아니면 안된다.
* 프로그램 잘 짠다고 글도 잘쓰는 것은 아니다. 훌륭한 프로그래머라고 해서 반드시 유능한 문학적 프로그래머가 되는 것은 아니다.


문서화툴
문서화를 도와주는 툴이 많이 있다는 말이다. 책에서는 Javadoc를 예로 들었는데 이는 다음과 같은 일을 도와준다.
 * 저작권 정보를 명시한다
 * 생성일자를 기록한다
 * 정보를 상호 참조시킨다
 * 오래된 코드에 deprecated라고 표시한다.(오래됐다고 바꾸라고 권장한다는 뜻)
 * 빠른 참조용의 짤막한 개요(synopsis)를 제공한다
 * 함수 파라미터 각각에 대한 설명을 제시한다
javadoc, C#의 NDoc와 Doxygen(www.doxygen.org)등이 있단다.
장점
* 코드의 문서화와 업데이트를 촉진
* 컴파일할 수 있는 코드를 위해 별도의 단계가 필요하지 않다(문학적 프로그래밍과의 차이)
* 비교적 자연스럽게 보인다.
* 문서화 툴은 풍부한 검색, 상호 참조, 코드 아웃라인 기능을 지원
단점
* API의 문서화에만 정말로 유용하고, 내부 코드의 문서화에는 일반 코멘트를 사용해야 함
* 소스 파일을 훑어보고 개략적인 내용을 파악하기 어렵다.(이런 건 문학적 프로그래밍이 한 수 위)
주의
* public 항목에 대해서는 하나 또는 두 개의 문장으로 구성된 설명을 작성하라. 쓸데없이 주절주절 늘어놓지 말란 말이다.
* 변수나 파라미터가 어디에 사용되는지 분명하지 않으면 문서화하라. 단 이름만 보아도 확실하게 알수 있으면 문서화하지 마라.
*함수 파라미터 중 어떤 것은 입력에 사용되고 어떤 것은 출력에 사용된다면, 그런 사실을 파라미터 설명에 명확히 기술하라
* 함수의 전제조건, 후행조건, 발생할 수 있는 exception, side effect를 모두 문서화 하라.

생각해보니 2학년 때 이현아교수님이 문서화 툴에 대해 언급했었고 임은기 교수님도 권장한 적이 있다. 다만 귀찮아서 사용하지 않았다. 잠시 알아본 적도 있었지만 귀찮아서 사용하지 않았다. 문서화 툴은 형식이 일정한 것이 아니라 툴 마다 다르기 때문에 필요하다면 실무에서 사용되는 공통된 것을 이용하면 될 것 같다. 사용법이 그리 어렵지 않으니 그때그때 필요한 것을 배우면서 사용할 수 있다. 문서화 툴에 의존하기보다는 필요한 정보는 코멘트로 달아두는 습관을 기르는 것이 더 도움이 될 것 같다.

+ 파일에는 헤더를 유지 (파일명, 목적, 저작권 [, 특이사항])
+ 함수에도 헤더를 유지 (parameter, return value, 목적)
+ 변수는 이름만으로 명확한 것이 아니면 반드시 설명(객체형식이라면 이름이 확실해도 설명을 붙여두는 것이 좋다.)

의미있는 이름을 사용하라.
변수, 타입, 파일, 함수등 모든 것들의 이름은 의미가 있는 것이어야 한다. x,y,z,a,b,c같은 이름들은 나중에 자신이 봐도 정확히 이해하기 어려울지도 모른다.

함수 작성 시 유의
- 하나의 함수는 하나의 동작! (동사로 이름짓는 것이 원칙)
- side effect를 최소화하라(side effect란 함수가 실행되는 도중에 외부에 있는 값이나 상태를 바꾸는 것을 말한다.)
-  짧게 만들라. 한 화면에 모두 들어갈 수 있도록 하되 코드를 짧게 만들기위해 무리하게 줄이지는 마라.

제약을 많이 가하라.
- const등을 이용해서 값이 바뀌면 안되는 것들은 모두 상수화해라.
- 양수만 가진다면 unsigned type을 사용하라. 귀찮다고 그냥 넘기는 경우가 많다.
- 몇가지 선택사항이 있다면 열거형식(enum)을 활용하라.
(가끔 생각하는데 boxing과 unboxing에 대한 것, 혹은 casting에 관한 것이 이러한 제약들과 겹칠 경우 어떻게 해야 하는가..하는 문제다. unsigned type의 변수를 선언했는데 signed형식을 parameter로 사용하는 method를 이용해야 할 경우 강제형변환(type casting)이 필요하다. 이러한 형 변환이 많이 사용될 때는 그냥 처음부터 signed로 하는게 좋지 않을까?)

마법의 수를 피하라.
코드내에 숫자가 들어가는 경우를 magic number라고 한다. if(counter == 76)과 같은 코드를 만나게 되면 76이 무엇을 뜻하는지 모르게 된다. #define과 같은 코드를 사용해서 문자상수를 사용할 수도 있고 상수를 선언해서 사용할수도 있다.
더욱 심한 경우를 초보자들이 많이 사용하는데 문자를 구분할 때 숫자를 적어버리는 경우가 있다. 이러한 경우는 C언어에 한해서 많이 나타나는 상황인데 특정한 문자인지 확인하기 위해 그 문자의 ASCII코드값을 적어버리는 경우가 있다. source를 유니코드를 사용하는 언어에 그대로 사용할 경우가 생길지도 모른다. 코드값이 다른 상황이 생길지도 모른다. 문자와 상수가 비교되지 않는 컴파일러를 만날지도 모른다.
코드에 숫자를 직접 넣어버리는 것은 피하도록 하자.

연관된 정보는 묶어라.
프로젝트의 크기가 커질수록, 코드의 길이가 길어질수록, 함수와 클레스가 많아질수록 분류의 중요성은 더욱 강조된다. 큰 물에서 놀고싶으면 애초에 큰 물에서 하는 습관을 들여놔야 한다.
- 한 콤포넌트를 위한 API는 한 파일안에 표현해야 한다.
- namespace나 package등을 이용하여 그룹화하라. 관계가 있는 상수들은 enum으로 정의하라.