[Clean Code/클린 코드] - 주석

목차

• 서론
• 주석은 양날의 검?
• 저자가 말하는 좋은, 나쁜 주석이란 무엇일까?

4장 주석

서론

주석이라는 chapter를 읽으면서 주석이 왜 필요한지에 대해 생각해보았습니다.

 

개발자가 작성하는 코드는 개발자의 배경과 경험, 지식 등을 반영하여 탄생합니다. 그래서 개인이 작성한 코드는 제 각각일 것입니다. 이러한 제 각각의 코드가 하나의 프로그램에 합해진 형태로 존재하는데, 만약 작성자에 비해 경험과 수준이 부족하거나, 다른 협력자들이 코드만 보고 작성자의 의도를 바로 이해할 수 있을까요?

 

아마 이해하는데 적지않은 시간이 소요되거나, 추가적인 설명 및 잘못된 네이밍으로 코드들은 직관적이지 못할 수 있습니다.

 

이럴 때 주석은 큰 힘을 발휘합니다.

 

일반적으로 주석은 작성한 코드에 타인이 이해하기 어렵거나, 해당 로직이 어떤 기능을 하고 있는지에 대한 추가 설명으로 많이 사용하고 있습니다. 덕분에 제 3자는 해당 로직을 전부 확인하지 않아도 주석만으로 코드의 역할을 직관적으로 이해할 수 있습니다.

 

그래서 주석은 직관적이어야 하고 필요한 정보만 담고 있어야 합니다. 필요로 하는 주석을 작성하기 위해 주석과 관련된 옳고 그름의 판단이 필요합니다. 이번 CHAPTER에서는 이러한 옳고 그름의 판단을 위해 학습 해보겠씁니다.

주석은 양날의 검?

“우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다.” (P.68)

 

만약에 제 3자가 직관적으로 “내” 코드 이해할 수 있다면, 주석은 필요할까?

여기에 관한 질문의 답은 ‘나’는 필요없다고 생각합니다. 직관적인 이름이나 좋은 네이밍을 가진 깔끔한 코드에서는 주석이 많이 필요하지 않을 것입니다. 주석이란 내 코드를 대변해주는 부가 설명느낌입니다.

 

주석이 많아지면 **코드가 길어져서** 향후 해당 코드를 찾아야 한다면 **오랜 시간을 소요**할 것입니다.

또한 주석으로 인한 **관리 포인트가 늘어날 것**입니다.
( 해당 코드를 사용하는 곳에도 주석을 추가해주어야 하기 때문에 만약 주석이 다른 언어로 작성되면?
또 그 **주석을 해석하는데 추가적인 노력이 필요**로 합니니다.)

 

이러한 문제로 주석을 사용하면 장점도 있지만, 단점도 있습니다. 주석은 우리가 작성하는 코드를 단지 조금 더 직관적으로 만들어 줄 뿐이지, **코드의 본질이 바뀌지 않았기 때문에 코드를 보완하는 것은 아닙니다.**

 

그래서 **Clean Code**가 필요한 이유입니다.

 

그래서 주석을 작성하기 전에 조금만 더 생각을 해볼 필요가 있습니다.

저자가 말하는 좋은, 나쁜 주석이란 무엇일까?

• 저자가 말하는 좋은 주석은 다음과 같습니다.
  1. 법적인 주석 ( 인정 )
     1. 저작권 정보 및 소유권 정보, 각종 규율에 따른 특정 주석의 명시가 필요한 경우
  2. 정보를 제공하는 주석
     1. 내 생각 : 정보가 진짜 필요한 주석이라면 모르겠는데, 굳이? 라는 생각이 들었다.
  3. 의도를 설명하는 주석
     1. 내 생각 : 굳이?
  4. 의미를 명료하게 밝히는 주석
     1. 내 생각 : 굳이?
  5. 결과를 경고하는 주석 ( 인정 )
  6. TODO 주석
     1. 내 생각 : 회사에서도 사용하는 것을 확인한 바 있음 → 필요하다고 생각한다.
  7. 중요성을 강조하는 주석
     1. 내 생각 : 코드에서 중요성을 강조할 일이 있나?
  8. 공개 API에서 JavaDocs
• 저자가 말하는 나쁜 주석은 다음과 같습니다.
  1. 주절거리는 주석
     • 마지못해 작성한 주석은 오히려 역효과 발생

     public void loadProperties()
     {
     	try
     	{
     		String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
     		FileInputStream propertiesStream = new FileInputStream(propertiesPath);
     		loadedProperties.load(propertiesStream);
     	}
     	catch(IOException e)
     	{
     		// 속성 파일이 없다면 기본값을 모두 메모리로 읽어 들였다는 의미이다.
     	}
     }
     

  2. 같은 이야기를 중복하는 주석
  3. 오해할 여지가 있는 주석
     • 주석만 보고 해당 프로세스를 이해하려다가, 주석이 잘못되어 있으면 오해의 여지가 생긴다.
  4. 의무적으로 다는 주석
     • 아래처럼 주석을 사용하면, 만약 내부가 조금만 바뀌면 주석 또한 바꿔야 하고, 괜히 이런 주석은 코드만 복잡하게 만듦.

     /**
     *
     * @param title CD 제목
     * @param author CD 저자
     */
     ...
     

  5. 이력을 기록하는 주석
     • 옛날의 관례에선 이러한 변경 이력의 기록이 중요했지만, 요즘엔 그렇지 않다. + 관리 포인트가 늘어날 것

     * 변경 이력 (11-Oct-2001부터)
     * ------------------------
     * 11-Oct-2001 : 클래스를 다시 정리하고 새로운 패키지인
     								com.jrefinery.date로 옮겼다 (DG);
     ...
     

  6. 있으나 마나 한 주석
     • 굳이 주석을 작성할 내용이 아닌데 주석을 작성한 경우

     /**
     	* 기본 생성자
     	*/
     protected AnnualDateRule() {
     }
     

  7. 무서운 잡음
  8. 위치를 표시하는 주석
  9. 닫는 괄호에 다는 주석
  10. 공로를 돌리거나 저자를 표시하는 주석
  11. 주석으로 처리한 코드
      1. 주석으로 처리한 코드는 삭제할 것 !
  12. HTML 주석
      • 소스 코드에서 HTML 주석은 혐오 그 자체다.
      • (Javadocs와 같은) 도구로 주석을 뽑아 웹 페이지에 올릴 작정이라면 주석에 HTML 태그를 삽입해야 하는 책임은 프로그래머가 아니라 도구가 져야 한다.
  13. 전역 정보
  14. 너무 많은 정보
  15. 모호한 관계
  16. 함수 헤더
  17. 비공개 코드에서 Javadocs