서론
보통 개발을 할 때 유지보수를 위해 주석을 달거나 또는 잊어먹지 않기 위해 적는 경우도 있다.
이번 챕터에서는 이러한 주석들이 올바르지 않게 사용하는 방법에 대해 지적하고,
올바른 사용 방법에 대해 강의한다. 이 강의를 듣고 필요한 부분을 정리한다.
Coding Standards에 대해
조직이 일정 수준의 크기가 되면 관료적인 문서화를 요구한다.
>> 필요하다.
대신, 결국엔 그 문서를 보기보단 소스 안에 해당 내용을 더 잘 녹일 수 있느냐가 중요하다. 코드내에서 명확하게 작성되어있지 않으면 헤매는 것은 문서가 되어있다해도 매 한가지다. (문서의 양은 광대하다.)
Coding Standards가 코맨트 작성을 강요하게 된다면
예시에서의 Comment 작성 부분을 보면,
메서드의 이름과 중복적인 내용을 써놓고, 인자의 변수 명만 봐도 알 수 있는 내용을 중복적으로 써놓은 것을 볼 수있다. 이렇게 작성하는 것은 무의미하다.
이러한 Comment들이 반복된다면 무시의 대상이되고 결국 유지보수를 하는 사람은 신뢰를 잃어 Comment를 안보게된다.
코맨트에 감사함을 느끼게해라. Comments should be rare !
Comment를 읽는 사람들이 감사함을 느끼게 만들어야한다.
이 말은 즉슨 하나의 Comment를 작성해도 신중하고 의미있게 설명하자는 것이다. 필자같은 경우도 한 부분에 신뢰를 한번 잃으면 관심도 안갖게 된다. 같은 의미로 생각해보자.
코맨트는 곧 실패를 말할 수 있다. Comments are Failures !
1. 작성자의 의도를 잘 나타나게 프로그램을 작성한다면 Comment는 불필요해진다.
2. 모든 메서드 변수마다 Comment가 작성이 되어있다면 당신의 코드가 expressive하지 못하다는 것을 나타낸다.
>> 실패의 상징 <<
Good Comments 모음
1. 라이센스를 나타내는 부분은 주석으로 나타내주는 것이 바람직하다.
2. 평범한 인자가 아닐 경우 comment에 인자 내용을 작성해주어 이해에 도움을 준다.
TODO를 작성해주어 IDE에서 관리할 수 있도록 만들어준다. (보통의 IDE에서 해당 기능을 지원해준다.)
Bad Comments 모음
1. 소스를 한번 읽으면 알 수 있는 내용을 주석으로 쓰는 것을 자제하자.
2. 의미없는 인자 값의 설명을 적었다.
3. 안 궁금하다. 아래의 이력은 다른 문서로 관리하자.
4. 이젠 아래 예제를 보면 당장 지우고 싶은 필요없는 주석들일 것이다.
5. 뚱뚱한 주석을 자제하자.
아래처럼 구분을 지어주는 것은 좋은데 너무 불필요하게 자리를 차지한다.
6. 필요에 의한 것이 아니라면 아래처럼 메서드에 작성자를 적는 행위를 자제하자.
마무리하며..
주석을 잘 작성하는 능력을 기르면 참 여러 사람을 행복하게 만들 수 있겠구나란 생각이 든다. 뒷 일을 생각하여 보다 좋은 코맨트로 우리의 개발을 이롭게 만들어보자
'Refactoring > Clean Coding Skill' 카테고리의 다른 글
| 클린코더스 강의 내용 정리 #003 - Function Structure (0) | 2022.04.08 |
|---|---|
| 클린코더스 강의 내용 정리 #002 - Function (0) | 2022.04.05 |
| 클린코더스 강의 내용 정리 #001 - OOP (0) | 2022.04.05 |
댓글