주석에 담아야 하는 대상

주석에 담아야 하는 내용은 코드가 무엇을 수행하는지에 대한 정보만 표현하는 것이 아니다 라는 생각을 가지게 해주는 장이다.

주석의 목적은 코드를 읽는 사람이 코드를 작성한 사람만큼 코드를 잘 이해하게 돕는데에 있다.

코드를 작성할 때 많은 귀중한 정보가 있는데 다른 사람들이 그 코드를 읽게 될때는 정보는 사라지기 마련이다. 왜냐면 내가 작성한 것이 아니기 때문에 그럴 것이다.

설명하지 말아야 하는 것

클래스 정의하는 부분부터 메소드, 필드 모두 빠짐없이 하나씩 다 주석을 달게되었을 때는 이미 코드를 읽는 사람도 알고있는 범위에 해당하므로 코드를 '더' 잘 이해하게 할수는 없어서 아무런 가치가 없다.

코드에서 빠르게 유추할 수 있는 내용은 주석 ❌
설명 자체를 위한 설명을 달지 말아야 한다.
함수의 선언과 주석 내용이 완전하게 일치하면 지우거나 개선해야할 사항이다.
그럼에도 주석을 달고 싶다면 더 중요한 사항을 적는 것이 낫다.

나쁜 이름에 주석을 달지마라 - 대신 이름을 고쳐라

다음은 언뜻 봤을때 CleanReply()라는 함수를 설명하는 것처럼 보인다.

// 반환되는 항목의 수나 전체 바이트 수와 같이
// Request가 정하는 대로 Reply에 일정한 한계를 적용한다.
void CleanReply(Request request, Reply reply);

주석은 clean이 의미하는 바를 설명했다. 이렇게 하려면 대신 한계를 적용한다는 부분을 메소드 명에 포함시켜야 한다는 것이다.

void EnforceLimitsFromRequest(Request request, Reply reply);

이러면 전보다 더 스스로 설명하는 것이 강해졌다. 좋은 이름은 함수가 사용되는 모든 곳에서 드러나기 때문에 좋은 주석보다 더 낫다.

그래서 프로그래머의 코드 규칙은 대개 좋은코드 > 나쁜 코드 + 좋은 주석 이다.

생각을 기록해라

이 부분은 머릿속에서 이 코드를 구현하는데에 있어서 생각했던 중요한 생각들을 그대로 적는것도 좋은 주석이 될 수도 있다고 한다. 이 주석으로 하여금 코드가 훌륭한지 아닌지도 판단할 수 있게 해준다.

개선이 필요할때나 코드가 불완전할때는 개선 아이디어를 설명하는 것이 바람직하다.
여기서 사용되는 표시가 몇 개 있다.

이런 것들을 사용하게 되면 훗날 어떻게 할지 생각이 들면 적재적소에 알맞게 활용하여 작성하는 일을 당연하게 받아들여야 한다. 그래야 코드를 읽는 사람에게 코드의 질이나 상태를 설명하고 추후 개선 방법을 제시하여 소중한 통찰을 제공할 수 있다.

상수에 대한 설명
상수는 정의가 되었을 때 상수가 어떤 것을 하는지, 왜 특정한 그 값을 가지고 있는지 이유가 있을 것이다. 그렇기 때문에 상수에 대해 별도의 설명을 해준다면 상수의 사용법을 알고 분석을 하는 입장에서 사용법을 명확하게 알게 되어 잘 활용할 수 있을 것이다.

코드를 읽는 사람의 입장이 되어라

이 책을 읽으면서 이번 5장 뿐만이 아니라 1장에서부터 계속 남의 시선에서 코드를 작성하는 것이 가장 깨끗한 코드라고 설명해주는 것 같다.
코드를 짤 때 혹시라도 어느 특정 부분에서 질문이 나올 느낌이 예상되는 곳에는 주석을 다는 것이 이해하기 쉽게 주석을 달아 이해를 높일 수 있을 것이다.
단점이 있는 로직을 사용할 때에는 사전에 실수를 방지하기 위해 주석을 다는것이 좋다. 단점을 스스로 깨닫게 하는 것보다 미연에 방지하는 방향이 더 좋다.

loop에 조건이 섞인 로직은 로직 내용을 요약하여 주석을 달아주는게 또 이해하는게 더 쉽다.
내 개인적으로도 for문이 많이 섞이면 여러개의 index가 머리를 꼬이게 만든다. 그래서 이부분은 되게 공감했던 내용이다.

생각하는대로 주석을 달고 그것의 단어 선택을 조금 완화시키면 완벽한 주석을 만들 수 있을 것이다.
5장을 읽은 이 순간부터 주석에도 신경쓰는 그런 개발자가 되어보자.