Chapter4. 주석
주석을 달 시간에 어떻게 코드를 더 잘 표현할지에 대해 고민하자.
4.0 주석은 필요악이다.
분명 좋은 주석도 있다. 하지만 우리의 주석은 보통의 경우
나쁜 주석일 가능성이 높다.주석을 다는 이유를 생각해보자. 나의 경우를 생각해보면 내가 작성한 코드를 상대방이 내가 의도한 대로 이해하기를 바라는 마음에 적는 경우가 많았다. 처음부터 다른 사람이 읽었을 때 의도한 대로 코드를 이해할 수 있게 작성해야 하는데 나는 그렇지 못했던 것이다.
또한 주석은 변화하는 코드에 따라가지 못하는 경우가 많다. 이것또한 많은 사람이 공감할 이야기라 생각한다. 혼자가 아닌 팀이 하는 프로젝트에 주석을 하나 달아 놓으면 그 주석은 미아가 되어버리는 경우가 많다.
4.1 주석은 나쁜 코드를 보완하지 못한다.
코드에 주석을 추가하는 일반적인 이유는 코드의 품질이 나쁘기 때문이다
만약 코딩을 하다
아 주석을 달아야 겠다!라는 생각이 들면 절대 주석을 달면 안된다.코드를 정리해야한다.
표현력이 풍부하고 깔끔하며 주석없는 코드가 주석이 여럿 달린 코드보다 훨씬 좋다.
자신이 저지른 난장판을 주석으로 설명하려 애쓰지 말고 난장팡을 깨끗이 치우는데 시간을 쓰자!
4.2 코드로 의도를 표현하라
분명 코드만으로 의도를 설명하기 어려운 경우가 존재한다. 하지만 시간을 들이면, 생각을 조금 더 해보면 분명히 코드로 대다수 의도를 표현할 수 있을 것이다.
4.3 좋은 주석
좋은 주석은 필요하거나 유익하다. 단 명심하라 우수한 주석은 달지 않을 방법을 찾아낸 주석이라는 사실을!
4.3.1 법적인 주석
법적인 내용, 저작권 소유권 정보는 필요하다.
4.3.2 정보를 제공하는 주석
기본적인 정보를 제공하는 주석인 편리하다. 주로 테스트 케이스에서 의미가 있다.
4.3.3 의도를 설명하는 주석
표현력이 풍부한 이름을 가진 함수가 있다고 해도 만약 코드를 같이 공유하지 않는 사람이 본다면 헷갈릴 여지는 충분히 있다. 이럴때는 코드의 의도를 설명하는 주석을 달면 좋다.
이미 표현력이 풍부한 함수였고 저자의 의도까지 설명이 되어있다면 코드를 처음보는 사람도 충분히 이해할 수 있을 것임.
4.3.4 의미를 명료하게 밝히는 주석
때때로 애매한 인수나 반환 값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다.
물론 우리가 직접 작성하는 함수들은 앞서 이야기한 부분을 다 표현력있게 해야한다.
단, 우리가 작성한 코드가 아니라
표준 라이브러리와 같이 이미 만들어져 있는 무언가를 사용할 때는 인수나 반환값이 애매할 때가 존재한다. 이런 경우에 주석을 달아서 그 의미를 명확하게 하는건 좋은 주석이다.
4.3.5 결과를 경고하는 주석
다른 프로그래메어게 결과를 경고할 목적으로 주석을 사용한다.
예를 들면 코드의 실행 결과로 무엇인가
삭제되거나수정되는 경우, 또는 실행시간이 매우 긴 경우가 있다.
4.3.6 TODO 주석
앞으로 할 일을//TODO주석으로 남겨두면 좋다.주의할 점은
//TODO주석을 남겨놓고 너무 오랫동안 방치하는건 좋지 않다.수시로
TODO주석을 점검하는 습관을 들이자
4.3.7 중요성을 강조하는 주석
자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위한 주석
4.4 나쁜 주석
대다수 주석이 이 범주에 속한다.
4.4.1 주절거리는 주석
특별한 이유 없이 의무감으로 혹은 작업 프로세서에서 하라고 하니까 마지못해 다는 주석을 절대로 시간낭비다.
만약, 주석을 무조건 달아야하는 상황이라면 충분한 시간을 들여서 최고의 주석 을 만들자.
4.4.2 같은 이야기를 줒ㅇ복하는 주석
이미 표현력이 충분한 함수를 만들어 놓았는데, 그 함수에 굳이 주석을 달아서 함수를 설명할 필요는 없다.
이런 주석은 함수보다도 더 많은 정보를 제공하지 못한다.
4.4.3 오해할 여지가 있는 주석
정확하지 않는 주석은 정말 최악이다...
나쁜 주석은 너무 많아서 이하는 생략한다. 결론은 왠만하면 주석을 달 시간에 어떻게 더 표현력 있게 코드를 작성할지를 고민하자.
Last updated