[Clean Code] 4장. 주석

주석은 때때로는 코드에 대한 부연 설명을 해주는 기능을 가지고는 있지만 시간이 지나면서 코드가 의도한 바가 아닌 내용을 부연 설명 할 수 있는 경우가 있다.

이와같이 부정확한 주석보다 차라리 없는 주석이 더 나으며 코드에다가 내용을 알기 쉽게 표현하는것이 더 중요하다.

하지만 가끔은 주석으로 표현할 수 있는 표기들이 있는데 이에 대하여 정리하여 보겠습니다.

 

좋은 주석

1. 법적인 주석

회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣어야 할 때 명시하는 주석

2. 의도를 설명하는 주석

코드를 작성함에 따라 결과는 동일하게 나타내지만 내부 구현에 따른 각자마다 차이점이 있을 수 있고 어떠한 의도로 내부 구현을 했는지 의도를 작성하는 의미로 쓰일 수 있다.

3. 의미를 명료하게 밝히는 주석

표준 라이브러리에서 사용하는 인수들의 이름이 애매한 경우에는 라이브러리를 사용하는 개발자가 좀 더 상세하게 알 수 의미를 적시할 수 있도록 주석을 다는것도 용이하다 하지만 주석에 올바르지 않은 정보를 적어 놓을 경우에는 더 혼돈이 올 수 있으므로 100% 정확한 정보가 아니라면 안적는걸 추천한다.

4. 결과를 경고하는 주석

테스트, 쓰레드 관리 등 특정 상황에서 어떠한 지식이 필요한 결과들을 주석으로 적어놓는 것도 해당 원인을 파악하기에 용이하다.

5. TODO 주석

앞으로 할 일을 TODO 주석으로 남겨두어 작성해놓고 코드를 작성하는 것도 용이하다 하지만 작업을 완료한 후 주석은 제거하며 주석을 관리하는것이 좋다.

6. 중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨지는 코드가 반드시 중요하다고 강조하기 위해 사용되는 주석도 적시할 수 있다.

7. 공개 API  Javadocs

설명이 잘 된 공개 API는 사용하기에 용이하다 하지만 javadocs를 보고 함에도 잘못된 정보가 있을 수 있으니 유의하여 사용해야 한다.

 

나쁜 주석

1. 주절 거리는 주석

특별한 이유 없이 프로세스를 적어놓거나 알 필요 없는 주석을 적어 놓는 주석은 바람직하지 않다.

2. 같은 이야기를 중복하는 주석

코드로 표현이 된 내용들을 다시 주석에다가 적어 같은 이야기를 하는 주석은 적지 않아야 한다.

3. 오해할 여지가 있는 주석

좋은 의도로 주석을 적어놨으나 정확하지 않아 오해를 할 여지가 있는 주석은 오히려 혼돈을 야기할 수 있다.

4. 이력을 기록하는 주석

변경이력을 기록하는 주석은 적지 않아야 하며 기록하고 싶다면 git 과 같은 소스 관리 시스템을 사용하라.

5. 함수나 변수로 표현할 수 있다면 주석을 달지 마라

6. 위치를 표시하는 주석

어떠한 기능들이 어디에 있다라는 표현하는 주석도 지양 하는것이 좋다

7. 닫는 괄호에 다는 주석

for문, if문 같은 body안에 구현들이 들어가고 닫는 괄호에 해당 구문이 종료된다는 주석을 적어놓는 것도 바람직 하지 않다

안에 내용들이 많이 들어가 있어 닫는 괄호를 찾기 힘들다면 함수를 쪼개어 관리하고 함수의 의도를 명확하게 하는것이 좋다.

8. 주석으로 처리한 코드

사용하지 않는 코드들을 주석처리하여 놨두는 코드는 좋지 않다 다른 사람이 보기에 중요한 코드니깐 남겼다 생각할 수도 있고 오히려 오해를 살 수 있는 코드가 되어버리기 때문에 자신이 임시로 놨두는 주석이 아닌 이상 소스 코드 관리 시스템에 올리기 전에는 모두 삭제하여야 한다.

9. HTML 주석

10. 전역 정보

소프트웨어에 전반적인 정보를 가지고 있는 것을 주석으로 달지 말아야 한다 전반적인 정보는 언제든지 바뀔 수 있고 바뀐 정보가 해당 주석에 항상 최신화 된다는 보장도 없기 때문이다

 

 

결론

필자가 생각하기로는 주석은 알고리즘이나 이미 법적으로 정해져 있는 명확한 사실, 간단해 보이지만 빠지면 절대 안되는 중요한코드 이상이지 않으면 명시하지 않는 것이 바람직 하다고 생각하며 주석보다는 코드에서 의도를 최대한 표현하고 코드로써 의미를 파악하게 하는 것이 중요하다고 생각합니다. 그러므로 항상 코드에 집중하여 소프트웨어를 개발함에 신경을 써야할 것이라 생각합니다.

 

 

해당 내용은 Clean Code를 읽고 정리한 내용입니다.

주관적인 생각과 내용을 같이 적시하였으니 적확한 정보는 해당 책을 통하여 같이 확인 해주시길 바랍니다.

http://www.kyobobook.co.kr/product/detailViewKor.laf?mallGb=KOR&ejkGb=KOR&barcode=9788966260959

Clean Code(클린 코드) - 교보문고