정지현

정지현

기술과 세상을 이어 소외된 사람들에게더 나은 환경을제공하고 싶은 개발자**

Tags

[개발도서] CleanCode 4장

2 분 소요

CleanCode 책 4장을 읽고…

주석

주석은 나쁜 코드를 설명하기 위해 존재하는 것이 아니다. 깨끗한 코드를 기반으로 정말 필요한 곳에 작성해야 하는 것이다. 그리고 가장 최선은 주석을 달지 않고 이해할 수 있는 코드를 짜는 것이다.

1. 글자값을 하는 주석

  • 법적인 주석

    • 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시하는 경우
    • 예시 ) 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보

  • 정보를 제공하는 주석

    • 기본적인 정보를 주석으로 제공하면 편리해지는 경우

      // 테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();

  • 의도를 설명하는 주석

    • 코드의 의도 설명을 통해 이해에 도움이 되는 경우

      // 스레드 대량 생산하는 방법으로 어떻게든 경쟁 조건을 만들려 시도한다.
for (int i = 0; i < 25000; i++) {
	WidgetBuilderThred widgetBuilderThread =
		new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
  Thread thread = new Thread(widgetBuilderThread);
  thread.start()
}

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

    • 표준 및 외부 라이브러리의 변경 못하는 코드에 속하는 경우, 모호한 인수나 반환값의 의미를 표현하면 이해에 도움이 된다.

      assertTrue(a.compareTo(a) == 0); // a = a
assertTrue(a.compardTo(b) != 0); // a != b

  • 결과를 경고하는 주석

    • 다른 프로그래머에게 결과를 경고할 목적으로 사용하는 경우

      // 여유 시간이 충분하지 않다면 실행하지 마시오
public void _testWithReallyBigFile()
{
	writeLineToFile(1000000);
	...
}

  • TODO 주석

    • 앞으로 할 일을 주석으로 남기는 경우

      // TODO-MdM 현재 필요하지 않다.
// 체크아웃 모델을 도입하면 함수가 필요 없다.
protected VersionInfo makeVersion() thrwos Exception
{
	return null;
}

  • 중요성을 강조하는 주석

    • 중요하지 않게 여겨질 코드의 중요성을 강조하는 경우

      String listItemContent = match.group(3).trim()
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.

2.글자값 못하는 주석

  • 주절거리는 주석

    • 이유 없이 의무감과 프로세스에 따라 마지못해 주석을 다는 경우

    • 아래 주석의 경우 “기본값을 모두 메모리로 읽다”에는 주체와 시점 등 중요한 정보들이 제외되어 있다. 이 코드가 의미가 있는 경우 해석을 위해 다른 코드를 뒤져봐야하는 수고로움이 생긴다.

      try
{
	...
	loadedProperties.load(propetiesStream);
}
catch(IOException e)
{
	// 속성 파일이 없다면 기본값을 모두 메모리로 읽어 들었다는 의미다.
}

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

    • 코드로 이해 되는 것을 주석으로 다시 설명하는 경우

      /**
 * 이 컴포넌트의 프로세스 지연값
 */
protect int backgroundProcessorDelay = -1

  • 의무적으로 다는 주석

    • 문서화를 위해 모든 코드에 주석을 다는 경우

    • 모든 변수에 의무적으로 주석을 다는 경우

      /**
 *
 * @param title CD 제목
 * @param author CD 저자
 */
public void addCD(strint title, String author){
  ...
}

  • 이력을 기록하는 주석

    • 모듈이나 코드의 이력을 관리하기 위해 다는 주석
    • Git같은 소스 코드 관리 시스템이 생겨 현재는 불필요한 주석이 됨

  • 위치를 표시하는 주석

    • 소스 파일에서 특정 위치를 표시할 때 쓰이는 주석

      // Action ////////////////////////////////////
protect int action{
...
}

  • 주석으로 처리한 코드

    • 필요없는 코드를 주석으로 남겨놓는 경우

      // InputStream resultsStream = formatter.getResultStream();
// SteramReader reader = new StreamReader(resultsStream)

  • 전역 정보를 표시한 주석

    • 해당 코드의 내용 외에 시스템 전반적인 정보를 기술하는 경우

      /**
 * 적합성 테스트가 동작하는 포트; 기본값은 <b>8082</b>
 *
 */
public void setFitnessPort(int fitnessPort)
{
	this.fitnessPort = fitnessPort;
}

3. 결론

주석 파트를 보면서 “주석으로 처리한 코드”, “위치를 표시하는 주석”을 많이 사용했던 내 코드를 돌아볼 수 있게 되었다. 그리고 “TODO 주석”과 “경고 주석”은 평소에 사용하지 않았던 것이기에 도움이 되는 주석에 대해서도 공부하는 기회가 되었다.

카테고리:

업데이트:

참고