주석과 커밋 메시지

주석은 what이 아니라 how와 why를 적어야 한다. 흔하게 보이는 주석의 유형이 아주 간단한 코드를 하나 또는 몇 줄까지 묶어 동작을 동어반복하는 것인데 교육용이 아니라면 이건 무용한 걸 넘어서 해롭기까지 하다. 동작 하나를 변경할 때 두 군데를 변경해야 한다? 이거 되게 많이 들어본 상황 아니야? 심지어 한 쪽을 고쳐도 다른 쪽을 고치지 않았을 때 자동으로 검출해낼 방법조차 없다. 하나의 의미 있는 동작으로 묶일 수 있는 단위를 함수로 빼지 않는 코드와 쉽게 이해할 수 있으며 의미 있는 이름을 붙이지 않는 코드는 이러나 저러나 영락없는 shit code이고, 그걸 주석으로 해결하겠다는 발상은 일단 참신하다고는 말하겠다. Javadoc이나 JSDoc 스타일로 함수와 클래스에 간단한 설명을 적는 것은 acceptable하지만, 역시나 how와 why가 없다면 좋은 주석으로 보기 힘들다.

커밋 메시지는 how나 why가 아니라 what을 적어야 한다. Refactor code는 최악의 커밋 메시지 중 하나이고, PR 리뷰 적용은 더 하다. fixed a bug는… 저들보단 낫지만 아직 모자라다. 커밋 메시지가 이러면 변경 추적이나 리버트가 끝도 없이 고달파진다. 이런 게 용인되는 조직이라면 커밋 내역이 저 꼴로 온통 범벅일 거거든. 근거로서 필연적 인과는 없지만서도 코드 베이스의 질도 분명히 엉망일 거라고 장담할 수 있다. 이런 제품은 커밋 로그만 훑고 있어도 난독화 거친 코드를 읽는 기분이 들게 된다.