주석에 대한 고찰

주석에 대한 의견

일하다 보면 주석에 대한 의견이 많이 갈린다
'주석은 코드의 이해를 방해하는 나쁜 것으로 주석을 달지 않기 위해 노력해야 한다' 라는 주장과
'주석은 코드의 유지보수성을 위해서 반드시 달아야 한다'
라는 두 의견으로 팽팽하게 맞선다.

개인적으로 둘다 맞다고 본다.
실제로 현업을 하면서 주석이 거짓말을 해서 크게 데인적도 있고, 주석이 없어서 모든 부분에 디버깅을 찍어보느라 개발시간이 예측한 것보다 오래 걸린적도 있다.

그렇다면 주석은 있는것이 좋을까? 없는것이 좋을까?

개인적인 생각으로는 과하지 않게 분석에 도움이 되는 주석은 좋은것 같다.

도움이 되는 주석이란

1. 인수인계 받은 사람이 시나리오 문서와 함께 보면 좋은 주석
   • 어떠한 2024.07.03 A 시나리오로 어쩌구 저쩌구 해야하기 때문에 이렇게 작성했다라는 주석
2. 함수가 하는 역할
3. 부득이하게 작성된 복잡한 if 문에 시나리오 설명과 쓰이는 변수에 대한 설명
   • 복잡한 if 문을 작성하지 않는것이 좋지만 실력이 안되거나 부득이한 경우 if 문에 사용되는 변수와 함께 시나리오 설명을 적어야 한다.
4. 현재 버전에서 더이상 사용하지 않는 필드를 삭제하지 않았다면 어떤 시나리오에 의해 사용하지 않는지
   • 이는 당장은 효용성이 없을수 있지만 해당 서비스를 대거 개편 할때 큰 도움이 된다.
5. 테스트 코드로서 개발기간에만 사용하고 개발 완료후 삭제해야할 코드에 대한 주석
6. 부득이하게 함수로 분리하기 어렵거나 분리하면 오히려 이해하기 어렵거나 수지타산이 안맞는 경우 계산하는 각 과정마다 어떠한 과정이라고 주석 달기
   • for 문 진입전, 또는 특정 시나리오 진입전, 도메인과 관련되 DB 작업 진입전

주석과 실력

주석을 달지 않으려면 실력이 필요하고 모두에게 공감되는 코드를 작성해야한다.
그렇지 못한다면 그런 코드를 작성하려고 노력하고, 실력이 안되면 주석이라도 열심히 달자.
그리고 자신을 코드를 이해 못하는 사람을 나무라기 전에 자기자신이 혹시나 코드를 이해하기 어렵게 작성한 것은 아닌가 한 번쯤 생각해보자.

정리

주석 없이 이해하기 쉬운 코드를 작성하는 것이 가장 바람직하나.

모두가 이해하기 쉬운 코드가 아니라면 주석을 달도록 하자.

이것이 코드의 유지보수성을 높히고, 나의 일을 줄이고, 작업 효율을 증대시키며, 코드의 수명을 길게 만든다.