주석에 대하여. 코드에 주석을 쓰냐마냐? 아니 제발 쓰자. 잘!

 

모두가 한 번씩은 읽어봤을 책 '클린코드'에서는 '주석을 지양해라'라고 하지만

제가 실무 하며 느낀 점은 '주석을 달아야 한다'입니다.

 

일단, 주석을 달지 말아야 하는 이유는 이렇습니다.

1. 불필요한 주석 때문에 코드가 지저분해진다.

2. 주석 내용과 실제 코드가 일치하지 않다(주석 관리가 잘 안 될 때)

3. 주석에 '어떻게'구현을 명시해 두면 발전이 없다

 

 

하지만 주석을 달아야 하는 이유는 아래 3가지입니다.

 

1. 영어 모국어가 아니다 보니... 읽고 이해하는 속도가 한글만큼 빠르지 않다.

2. 메서드 로직을 하나 파악하려면 코드를 다 뜯어봐야 한다 -> 주석을 달면 주석만 보고 불필요한 메서드는 바로바로 넘어갈 수 있다

3. 코드 이해도를 확 올린다.

 

 

단!! 그냥 막 달면 당연히 안됩니다.

 

클린코드에서 주석을 달지 말라고 한 이유도 다 있으니까요.

 

주석 달 때 필수로 고려사항

1. '어떻게' 구현하느냐가 아닌, '무엇'을 구현하는지 명시하기

    어떻게 구현할지는 신규 구축 or 유지보수 할 사람에게 맡겨야 한다. 구현방법은 제외하고 '무엇'을 해야 하는지만 명확하게 작성한다.

2. 주석으로 수다 떨지 말기.

    본인이 이걸 개발하기 위해 얼마나 힘들었고, 개발 과정은 어땠고, 등등 불필요한 말은 제거한다

3. '남이 봤을 때' 이해하기 쉽게 작성하기

    글을 쓰면 '나' 중심으로 작성하게 된다. 나 혼자 보는 코드면 상관없다. 하지만 팀원/회사동료들이 보고 관리할 코드는 이제 더 이상 내 코드가 아니다. 내가 아닌 '남'이 봤을 때 이해가 되도록 작성한다.

4. 필요하면 링크도 건다.

5. 내가 작성한 주석이 아니더라도 코드랑 다른 내용이 있으면 적극적으로 수정한다(코드 주인의식)