TIL (2022.01.29)

DAY 9

🔖 오늘 읽은 범위 : 4장, 주석 (~ p.94 나쁜 주석)

😃 책에서 기억하고 싶은 내용을 써보세요.

• 나쁜 주석
  • 주절거리는 주석
    • 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.
    • 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다.
  • 같은 이야기를 중복하는 주석
    • 주석이 코드보다 더 많은 정보를 제공하지 못한다.
  • 오해할 여지가 있는 주석
    • 때때로 의도는 좋았으나 프로그래머가 딱 맞을 정도로 엄밀하게는 주석을 달지 못하기도 한다.

      // this.closed가 true일 때 반환되는 유틸리티 메서드다. 
      // 타임아웃에 도달하면 예외를 던진다.
      public synchronized void waitForClose(final long timeoutMillis) throws Exception { 
      	if ( ! closed ) { 
      		wait ( timeoutMillis ) ; 
      		if ( ! closed ) 
      			throw new Exception("MockResponseSender could not be closed"); 
      	} 
      }

    • (코드보다 읽기도 어려운) 주석에 담긴 ‘살짝 잘못된 정보’로 인해 this.closed 가 true로 변하는 순간에 함수가 반환되리라는 생각으로 어느 프로그래머가 경솔하게 함수를 호출할지도 모른다.
  • 의무적으로 다는 주석
    • 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다. 이런 주석은 코드를 복잡하게 만들며, 거짓말을 퍼 뜨리고 혼동과 무질서를 초래한다.
  • 이력을 기록하는 주석
    • 예전에는 모든 모듈 첫머리에 변경 이력을 기록하고 관리하는 관례가 바람직했다. 당시에는 소스 코드 관리 시스템이 없었으니까.
    • 하지만 이제는 혼란만 가중 할 뿐이다. 완전히 제거하는 편이 좋다.
  • 있으나 마나 한 주석
    • 쉽게 말해, 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이다.

      /** 
      * 월 중 일자틀 반환한다. 
      * 
      * @return 월 증 일자
      */
      public int getDayOfMonth () { 
      	return dayOfMonth ; 
      }

    • 위와 같은 주석은 지나친 참견이라 개발자가 주석을 무시하는 습관에 빠진다. 코드를 읽으며 자동으로 주석을 건너뛴다.
    • 있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리하라.
  • 무서운 잡음
  • 함수나 변수로 표현할 수 있다면 주석을 달지마라

    // 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
     if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) 

    • 이 코드에서 주석을 없애고 다시 표현하면 다음과 같다.

      Arraylist moduleDependees = smodule.getDependSubsystems(); 
      String ourSubSystem = subSysMod.getSubSystem(); 
      if (moduleDependees.contains(ourSubSystem))

  • 위치를 표시하는 주석

    // Actions //////////////////////////////////

    • 일반적으로 위와 같은 주석은 가독성만 낮추므로 제거해야 마땅하다.
    • 그러므로 반드시 필요할 때만, 아주 드물게 사용하는 편이 좋다. 배너를 남용하면 독자가 혼한 잡음으로 여겨 무시한다.
  • 닫는 괄호에 다는 주석
    • 중첩이 심하고 장황한 함수라면 의미가 있을지도 모르지만 (우리가 선호하는) 작고 캡슐화된 함수에는 잡음일 뿐이다.
    • 그러므로 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도하자.
  • 공로를 돌리거나 저자를 표시하는 주석
    • 소스 코드 관리 시스템은 누가 언제 무엇을 추가했는지 귀신처럼 기억한다. 저자 이름으로 코드를 오염시킬 필요가 없다.
  • 주석으로 처리한 코드
    • 1960년대 즈음에는 주석으로 처리한 코드가 유용했었다. 하지만 우리는 오래 전부터 우수한 소스 코드 관리 시스템을 사용해왔다. 소스 코드 관리 시스템이 우리를 대신해 코드를 기억해준다.
  • HTML 주석
    • 소스 코드에서 HTML 주석은 혐오 그 자체다.
  • 전역 정보
    • 주석을 달아야 한다면 근처에 있는 코드만 기술하라. 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.
  • 너무 많은 정보
    • 주석에다 홍미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라.
  • 모호한 관계
    • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
    • 주석을 다는 목적은 코드만으로 설명이 부족해서다. 주석 자체가 다시 설명을 요구하니 안타깝기 그지없다.
  • 함수 헤더
    • 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
  • 비공개 코드에서 Javadocs
    • 시스템 내부에 속한 클래스와 함수에 Javadocs를 생성할 필요는 없다.
  • 예제
    • 아래 모듈이 매력적인 이유는 우리들 상당수가 이런 코드를 보면서 ‘주석을 잘 달았다’고 생각하던 시절이 있었기 때문이다.

🤔 오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

• 코드를 짜는 일은 어린 아이에게 설명하는 것과 같다고 생각한다. 어른이라면 하나의 어려운 문장도 이해할 수 있지만, 아이에게는 쉬운 여러 개의 문장으로 설명해야 한다. 즉, 나에게는 내가 작성한 한 줄의 주석이 더 편하게 느껴질지라도, 나의 코드를 처음 보는 사람에게는 모든 것이 생소하게 느껴질 수 있다. 그것이 우리가 한 줄로 주석을 남기고 끝내는 것이 아니라, 코드를 여러 줄로 풀어쓰는 데 더 공들여야 하는 이유인 것 같다.

🔎 궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

• 소스 관리 시스템(= 버전 관리 시스템, VCS)
  • 프로그래밍 소스 관리 시스템
  • 의미 있는 변화들의 기능 개선과 버그 수정, 요구 사항에 따른 프로그래밍 소스 수정을 관리하는 버전 관리
  • ex. CVS(동시 버전 시스템), Subversion, Mercurial, Git 등...
  • 참고 링크: VCS - 버전관리 시스템에는 어떤것들이 있을까?
• Javadoc
  • 코드를 작성하다 보면 유지보수, 배포 등 다양한 상황으로 인해 코드의 문서 작성이 필요한 경우가 있습니다.
  • 문서화할 클래스, 필드, 메서드, 어노테이터, 인터페이스 등에 주석 및 어노테이션으로 문서를 작성하고, HTML등 다양한 포맷으로 export 하는 기능을 제공합니다.
  • 참고 링크: Javadoc 작성하기

소감 3줄 요약

• 주석이 코드보다 더 많은 정보를 제공하지 못한다.
• 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.
• ‘주석을 잘 달았다’의 기준은 시간이 지남에 따라 바뀐다. (미래에는 주석이란 게 없어질 수도 있지 않을까.)