좋은 코드 작성하기 - 코드는 이해하기 쉬워야 한다. (3)

[미학]

- 선언문을 블록으로 구성하라

1 2 3

void add(n1, n2); void saveData(); void del(n1, n2);

위 코드는 깔끔해보이지만 이게 몇십줄 되가면 복잡해집니다.

이럴땐 코드들을 블록으로 나누어 정리한다면 더 깔끔해집니다.

1 2 3 4 5 6

// calculate void add(n1, n2); void del(n1, n2);   // processing Data void saveData();

이럴땐 코드들을 블록으로 나누어 정리한다면 더 깔끔해집니다.

[ 주석 ]

주석은 참 있으면 좋은데 그렇다고 너무 많으면 안좋고 애매한 녀석인데요. 최대한 이롭게 쓰는 방법을 알아봅시다.

- 설명하지 말아야 하는 것

(1) 함수명을 하나의 문장으로 정리한꼴 밖에 안되는 경우

1 2 3 4 5 6 7

// 주어진 이름과 깊이를 이용해서 서브트리에 있는 노드를 찾는다. Node* FindNodeInSubtree(Node* subtree, string name, int depth);   // 주어진 'name'으로 노드를 찾거나 아니면 NULL을 반환한다. // 만약 depth <=0 이면 'subtree'만 검색된다. // 만약 depth == N 이면 N 레벨과 그 아래만 검색된다. Node* FindNodeInSubtree(Node* subtree, string name, int depth);

위 코드의 첫번째 경우를 보면 그냥 함수를 알아차리기 쉬움에도 불구 하고 서술해 쓸데없는 주석일뿐입니다.

이런 코드에는 주석이 그리 필요해보이지 않으나 두번쨰 경우처럼 세부사항을 적어준다면 개발자들의 빠른 이해를 도와줄것입니다.

(2) 나쁜 이름을 주석으로 해결하려 드는 경우

1 2 3 4

// loadData()가 받아온 데이터를 암호화하는 함수 void enigma();   void EncodeData();

애니그마가 암호화랑 관련이 있다고는 하지만 이런식으로 작성하는것은 코드의 낭비입니다.

차라리 두번째 줄처럼 직관적으로 알 수 있게 해주는것이 훨 났습니다.

(3) 코드에 있는 결함을 설명하라 

개선이 필요하지만 못 고친것을 창피하게 여기지 마세요.

당당히 개선할점을 주석으로 달아주셔야 고쳐주기도 편하니까요.

몇가지 널리 사용되면 표시를 알려드리자면

 // TODO: -> 아직 하지 못해서 해야되는 일

// FIXME: -> 오작동을 일으키나 수정을 못하거나 안한 코드

// HACK: -> 해결을 하긴했는데 뭔가 불안하게 한 코드

// XXX: -> 위험! 여기 큰 문제가 있다!

(4) 상수를 설명해줘라

const int NUM_THREADS = 8;

이 상수는 별도의 설명이 필요없어 보이지만 

const int NUM_THREADS = 8; // 이 값이 2*num_processors보다 크거나 같으면 된다.

이렇게 설명이 있다면 상수값을 변경할때 더 이로울 것이다.

(5) 요약 주석 

긴 함수인데 이게 몇개의 큰 덩어리로 나누어질수 있다면 요약주석도 유용합니다.

1 2 3 4 5 6 7 8 9 10

void GenerateUserReport() {   // 이 사용자를 위한 lock을 얻는다.   ...   // 데이터베이스에서 사용자의 정보를 읽는다.   ...   // 정보를 파일에 작성한다.   ...   // 사용자를 위한 lock을 되돌려 넣는다.   ...   }

처음 온 신입사원도 이런 주석들을 보면 코드를 쉽게 이해할 수 있겠죠?