클린코드 4장 : 주석

0. 일반적인 생각

코드로 의도를 표현하지 못해 주석을 사용한다고 생각, 부정확한 주석은 결코 이뤄지지 않을 기대를 심기도 한다.

아래는 OOP(Object-oriented programming)에서 생각하는 주석 내용에 대해 정리해 보았다.

클린코드 책에서 나온 주석에 관한 생각들을 요약해보았다.

1. 주석은 나쁜 코드를 보완하지 못한다.

: 표현력이 풍부하고 깔끔하며 주석이 없는 코드(better) > 복잡하고 어수선하며 주석이 많이 달린코드(worse)

2. 코드로 의도를 표현하라

주석이 있는게 중요한게 아니라, 코드로 의도가 표현되면 된다

ex) 

//직원에게 복지혜택을 받을 자격이 있는지 검사한다.

if((employee.flags & HOURLY_FLAG) && (employee.age >65))

-> if(employee.isEligibleForFullBenefits()) : 주석은 없지만 이게 깔끔하다.

3. 좋은 주석

1) 법적인 주석

: 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시함

ex) 저작권 정보와 소유권 정보 등

-> // Copyright (c) 2017 Felix Company, ...

2) 정보를 제공하는 주석

: 기본적인 정보를 주석으로 제공하면 편리

ex) 

//테스트 중인 Responder 인스턴스 반환

protected abstract Responder responderInstance();

3) 의도를 설명하는 주석

: 때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명함

4) 의미를 명료하게 밝히는 주석

: 모호한 인수나 반환값은 그 의미를 읽게 좋게 표현하면 이해가 쉬워짐

: 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용

ex) 

WikiPagePAth a = PathParser.parse("PageA");

assertTrue(a.compare(a) == 0); // a == 1

5) 결과를 경고하는 주석

ex) 예를 들면 여유시간이 충분하지 않다면 실행하지 마세요라고 추가

6)TODO 주석

: 앞으로 할일을 //TODO 로 남겨두면 편함

7) 중요성을 강조하는 주석

: 말그대로 뭔가 중요성을 강조하기 위해 주석을 사용

8) 공개 API에서 Javadocs

: 설명이 잘된 공개 API는 참으로 유용하고 만족스러운데 표준 자바 라이브러리에서 사용한 Javadocs이 가장 좋은 예

# 그러나 Javadocs도 독자를 오도하거나 잘못위치하거나 그릇된 정보를 줄 확률이 있음

4. 나쁜 주석

: 대다수 주석이 이 범주에 속함

1) 주절거리는 주석

: 특별한 이유없이 프로세스에서 하라고 하니 마지못해 주석을 단다면 시간 낭비

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

: 간단히 해석 가능한 곳에 주석은 필요 X

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

: 때때로 의도는 좋았으나 프로그래머가 딱 맞을 정도로 엄밀하게 주석을 달지 못함

4) 의무적으로 다는 주석

: Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석은 것 

-> 이런 주석은 코드를 복잡하게 만들고 거짓말을 퍼뜨리며 혼동을 가중시킴

# Jacdocs란?

- Javadoc은 문서생성자 (documentation generator) 임 (by wikipedia)

 (API를 쉽게 생성할 수 있도록 도와줌)

- /** 로 시작해서 */ 로 끝남

- 사용하는 경우 : Interface, class, member function, variable 위에 선언

- 위의 경우에 /** 하고 엔터를 치면 자동으로 생김

Javadoc 태그에는 

@param : 파라미터에 대한 간략한 설명 @return : 리턴 값에 대한 간략한 설명 @author : 소스코드를 작성한 사람 @deprecated : 사용추천안함 @see : 참조되거나 관련있는 클래스 표시 @version : 소스코드 버전 정보 @since : 소스코드가 적용된 버전

5) 이력을 기록하는 주석

: 예전에는 git 등 소스 코드 관리 시스템이 없어서 예전에는 이력을 주석으로 썼지만

이제는 혼란만 가중시킬 수 있음

6) 있으나 마나 한 주석

: 때때로 있으나 마나 한 주석을 접하는데, 새로운 정보를 제공하지 못하는 주석은 없어져야 함

7) 무서운 잡음

: 때로는 Javadocs도 잡음

-> 전부다 일관적으로 주석을 달필요 없음. 필요한 것만 달자!

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

: 위의 말 그대로다.

ex) //Action /////////////

/ (슬래시) 를 많이 쓰면 눈에 띄어서 주의를 환기하는 효과가 있음(다른 것들에 대해 가독성을 낮춤)

-> 그러나 이렇게 튀는 만큼 아주 드물게 사용하는 것이 좋음

9) 닫는 괄호에 다는 주석

: 때로 프로그래머는 닫는 괄호에 특수한 주석을 달음

: 닫는 괄호 옆에 주석을 다는 경우도 있지만 좋은 것은 아님

ex)

public int sum(int firstNumber, int secondNumber){

int result = firstNumber + secondNumber;

return result;

} // sum -> 이런 것...

10) 공로를 돌리거나 저자를 표시하는 주석

: 저자 이름으로 코드를 오염시키지 마라

-> 소스 코드 관리 시스템은 누가 언제 무엇을 추가했는지 남겨져 있기 때문

ex) /* added by Felix */ 

11) 주석으로 처리한 코드

: 프로그래머는 작업하다가 변수나 함수 등 이러한 코드들을 주석으로 남기기도 한다

-> 다른 사람들이 지우기를 주저함. 이유가 있어서 지우면 안된다고 생각함

12) HTML주석

: 소스코드에서 HTML주석은 혐오 그 자체

: Javadocs 같은 도구로 주석을 뽑아 웹 페이지에 올릴려면 주석에 HTML태그를 삽입하는 것은 프로그래머가 아니라 도구가 져야함

13) 전역정보

: 주석을 달아야 한다면 근처에 있는 코드만 기술해라

: 전반적인 정보를 기술하지 마라

14) 너무 많은 정보

: 주석에 역사나 관련없는 정보를 장황하게 늘어놓지 마라.

14) 모호한 관계

: 주석과 주석이 설명하는 코드 둘 사이는 명백해야 함

: 때때로 주석과 코드가 매치 되지 않는 경우가 있으니 주의해야함

15) 함수 헤더

: 짧은 함수는 긴 설명이 필요 X

-> 짧고 한가지만 수행하며 이름을 잘 붙인 함수는 주석으로 헤더를 추가한 함수보다 훨씬 좋음

16) 비공개코드에서 Javadocs

: 공개 API는 Javadocs가 유용하지만 공개하지 않을 코드라면 Javadocs는 쓸모가 없음

-> Javadocs 주석이 요구하는 형식으로 인해 코드만 보기 싫고 산만해지기 때문