코드에 주석은 필요한가

아래 내용은 지극히 개인적인 개발에 대한 의견 입니다 관련해서 반대하거나 논란의 여지가 있을 수 있으며 정답이 아닐 수 있습니다

코드에 남은 주석 유형

> 코드였는데 주석입니다만?

레거시 코드엔 흔히 코드 였는데 주석인 묘비들이 종종 보인다 이럴때 이게 삭제 되도 될지 어떤 의도로 남겨둔건지.. 과대 해석 하게 될 수도 있다

레거시 코드에서 코드블럭을 주석으로 처리하는 개발자의 마음으로 한번 바라보자

왜 그는 코드블럭을 함수를 주석으로 뒀을까

1. 리펙토링 과정에서 기존 코드를 보고 싶어서
2. 리펙토링 이후 문제시 기존 코드로 되돌리고자
3. 구현했지만 사용하지 않는다 하지만 구현해둔게 너무 아깝다…. 그래서 일단 주석으로 남겨둔다 다음에 쓸거같다…
4. 내가 제거한 코드를 전리품으로 남기기

코드가 주석이 되는 순간 그 코드는 빌드 되지 않고 리펙토링 시 추상화된 인터페이스 변경을 따라가지 않을 것이며 변수 명 조차 따라 바뀌지 못한다 코드를 주석으로 두는 것은 딱 고치는 과정에서만 유지하자

요즘 vcs에서는 히스토리 추적도 용이하고(git blame너무 잘나온다) 사실 코드를 테스트 잘 하고 잘 짜면 .. 된다

> pseudo code 작성하며 남긴 로직 주석 이나 코드에 대한 설명

아 친절해라

다시 보면 코드 안봐도 코드가 읽힌다

근데 코드와 주석 내용이 다르다…

왜 다를까?

당연히 좋은 개발자 라면 리펙토링 과정에서 주석도 같이 고쳐 둬야 하지만 대다수가 그렇진 않다 주석은 고치지 않아도 동작하고 vcs 에서 아무런 거부 없이 받아 들인다

꼭 필요한지 다시한번 생각하자 잘 구현해 함수명 변수명 으로 잘 포장했다면 주석은 불필요하다

주석을 봐야 내 코드가 이해된다면 변수명 주석 구조 가 잘못되진 않았는지 의심해보고 주석을 지우도록 하자

나 이외의 개발자에게 아무런 도움이 안된다

꼭남겨야 할 주석은 그런 내용이 아니다

> 수식이나 논문 스펙 라이브러리의 복잡함에 대한 원문을 옮겨 둔 내용

이런 내용은 사실 주석이나 링크로 남겨두어도 괜찮다
그리고 이후에 다른 수식/논문 다른 내용으로 변화하게되면 꼭 주석도 같이 고쳐 주어야 맞다
구현의 의도가 어느 것에 의존한 내용이라면 그 내용에 대해서 변화하거나 내용이 도움 되지 않거나 코드와 다르게 흐르는 자체가 비정상적인 상황이다

예를 들면 sha256 에 대한 구현을 담은 함수의 위에 sha256 을 구현 하는 스펙에 대한 주석이 있다면
매우 정상적이고 다른 개발자들 에게도 도움이 된다

> 수정한 이유와 날자 와 내 이름을 적어둔 주석

요즘엔 사실 보기 힘들지만 레거시 코드에선 흔히 보이던 주석이다

vcs 는 그저 보관용일 뿐 코드에 대한 형상 관리는 주석으로 하던 시절….

매우 안 좋은 습관지 않나 싶다..
위 내용들과 마찬가지로 코드와 이격 되며 텍스트엔 보통 주저리 주저리 쓸모없는 대사들을 친 경우들이 잦다
//집에가고싶다
라던지…..

git 이 어려우면 gui 툴을 꼭 쓰자.. 공짜로 소스트리라던지 소스트리 라던지..