10가지 코드 주석과 서식 습관

출처: 10 Best Practices of Code Commenting & Formatting

코드 주석과 서식은 코드를 이해하기 위한 것이다. 코드의 이해는 유지보수와 밀접하게 관계있다.

주석

1. "요구되는" 주석을 사용하라
1. 라인마다 불필요한 주석은 가독성을 떨어뜨린다
1. int count = 0; // 0을 초기값으로 count에 할당한다(?!?)
2. 주석의 부족은 유지보수 시간을 증가시킨다. 또한,  변수/메소드  이름을 이해될 만하고 스스로 설명을 하도록 짓는다
1. int s = sqrt(v1) + v2 / v3 + fread(s). getChar(0) //(?!?)
2. List<int> getVal(int val, int len, String op) //(?!?)
2. 틀린 주석을 작성하지 마라. 틀린 설명은 없는 주석보다 나쁘다
3. 변수가 중요하거나 스스로 설명하는 이름을 지을 수 없으면 주석을 작성하라
4. 공개 메소드의 주석을 작성하는 것은 좋은 습관이다. 물론, 이 주석들은 "정말 필요"하고 "요구되는" 것이어야 한다
5. "깨달음(gotcha)"와 "할 일(todo)"는 발견 즉시 문서화하라. 이것들은 훗날 현재를 기억하는데 도움이 될 것이다. 문서화하지 않으면, 당장 내일만 되도 기억하지 못 할 것이다. 결국 문제 있는 코드는 계속될 것이다

서식

1. 괄호는 일관성있게 사용하라. 열린 괄호를 현재 라인 끝에 놓던지 새로운 라인 처음에 놓던지 일관성을 유지하라
2. 요구되는 빈 라인을 일관성있게 사용하라. 빈 라인은 코드들을 가독성을 위해 의미적으로 분리하기 위해서 사용한다. 예를들어, 메소드 끝에 3줄 빈 라인, 빈 줄 없는 코드 또는 각 라인 마다 1~2줄 빈 라인은 가독성을 떨어뜨리고 눈에도 안 좋다.
3. 들여쓰기에 주의하라. 명령문 그룹을 위한 올바른 들여쓰기는 괄호와 빈 라인을 사용하는 것만큼 중요하다
4. 한 라인의 글자수는 가독성을 위해 제한하라. 보통 80자다. 그러나 약간을 조절될 수 있다
5. 코드 사이에 빈칸을 일관성있게 사용하라. 빈칸 사용의 적합한 상황은 다음과 같다
1. 연산자와 피연산자 사이
   a += b , c = 0; (a == b)
2. 명령문 키워드와 괄호 사이
   if (value) {, public class A {
3. 루프에서 ';'글자 다음에
   for(int i = 0; i < length; i++)
4. 타입 변환자와 피연산자 사이
   (int) value, (String) value

나의 생각

한가지 추가하고 싶은 서식이 하나 있다

1. 변수는 최대한 사용하기 바로 전에 선언하라

이는 가독성을 올려주고, 리펙토링 시에도 도움이 된다. 이 습관을 그대로 따를 필요는 없지만, 어떤 형태로든 위의 습관들에 대해서 팀내 합의를 통해 결정을 하고 일관성있게 유지하도록 노력해야한다

서식의 경우, AStyle과 Google Cpplint로 C++ 코드 스타일 자동화하기를 참고하자