DAY 8

오늘 공부한 범위 : 4장. 주석

📘 책에서 기억하고 싶은 내용

• (p.68) 우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다. 그래서 주석은 반겨 맞을 손님이 아니다.
• (p.69) 나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다.
• (p.70) 코드로 의도를 표현하라!
  • 나쁜 코드

  // 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
  if((employee.flags && HOURLY_FLAG) && (employee.age > 65))

  • 좋은 코드

  if(employee.isEligibleForFullBenefits())

• (p.70~74) 좋은 주석
  • 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실!
  • 법적인 주석
    • 소스 파일 첫머리에 들어가는 주석이 반드시 계약 조건이나 법적인 정보일 필요는 없다. 가능하다면, 표준 라이선스나 외부 문서를 참조해도 되겠다.
  • 정보를 제공하는 주석
    • 기본적인 정보를 주석으로 제공하면 편리하다. 그렇다 할지라도, 가능하다면, 함수 이름에 정보를 담는 편이 더 좋다.
    • 주석이 달린 예제 코드

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

    • 함수명을 변경해 주석 없애기

    portected abstract Responder responderBeingTested();

  • 의도를 설명하는 주석
  • 의미를 명료하게 밝히는 주석
    • 주석이 올바른지 검증하기 쉽지 않다. 이것이 의미를 명료히 밝히는 주석이 필요한 이유인 동시에 주석이 위험한 이유이기도 하다.
  • 결과를 경고하는 주석
  • TODO 주석
    • 하지만 어떤 용도로 사용하든 시스템에 나쁜 코드를 남겨 놓는 핑계가 되어서는 안된다.
    • 주기적으로 TODO 주석을 점검해 없애도 괜찮은 주석은 없애라고 권한다.
  • 중요성을 강조하는 주석
  • 공개 API에서 Javadocs
• 나쁜 주석
  • 주절거리는 주석
  • 같은 이야기를 중복하는 주석
    • 실제로 코드보다 부정확해 독자가 함수를 대충 이해하고 넘어가게 만든다.
    • 예시코드
      목록 4-2 ContainerBase.java(톰캣)

    public abstract class ContainerBase
    	implements Container, Lifecycle, Pipeline,
        MBeanRegistration, Serializable {
        	/**
            * 이 컴포넌트의 프로세서 지연값
            */
            protected int backgroundProcessorDelay = -1;
            
         	/**
            * 이 컴포넌트를 지원하기 위해 생명주기 이벤트
            */
            protected LifecycleSupport lifecycle = 
            	new LifecycleSupport(this);
                
         	/**
            * 이 컴포넌트를 위한 컨테이너 이벤트 Listener
            */
            protected ArrayList listeners = new ArrayList();
            
            ...
            
         	/**
            * 컨테이너와 관련된 DirContect 객체
            */
            protected  DirContext resources = null;     

  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
    • 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다.
    • 이런 주석은 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래한다.
    • 예전에는 모든 모듈 첫머리에 변경 이력을 기록하고 관리하는 관례가 바람직했다. 당시에는 소스 코드 관리 시스템이 없었으니까. 하지만 이제는 혼란만 가중할 뿐이다. 완전히 제거하는 편이 좋다.
  • 있으나 마나 한 주석
  • 무서운 잡음
    • 때로는 Javadocs도 잡음이다.
  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라
    • 나쁜 코드

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

    • 좋은 코드

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

  • 위치를 표시하는 주석
    • ex) // Actions ////////////////////////////////
    • 위와 같은 배너 아래 특정 기능을 모아놓으면 유용한 경우도 있긴 있다. 하지만 일반적으로 위와 같은 주석은 가독성만 낮추므로 제거해야 마땅하다. 특히 뒷부분에 슬래시로 이어지는 잡읍은 제거하는 편이 좋다.
    • 그러므로 반드시 필요할 때만, 아주 드물게 사용하는 편이 좋다.
  • 닫는 괄호에 다는 주석
    • 중첩이 심하고 장황한 함수라면 의미가 있을지도 모르지만 (우리가 선호하는) 작고 캡슐화된 함수에는 잡음일 뿐이다.
    • 그러므로 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도하자.
  • 공로를 돌리거나 저자를 표시하는 주석
    • 이러한 주석의 정보는 소스 코드 관리 시스템에 저장하는 편이 좋다.
  • 주석으로 처리한 코드
    • 1960년대 즈음에는 주석으로 처리한 코드가 유용했었다. 하지만 우리는 오래전부터 우수한 소스 코드 관리 시스템을 사용해왔다. 소스 코드 관리 시스템이 우리를 대신해 코드를 기억해준다. 이제는 주석으로 처리할 필요가 없다. 그냥 코드를 삭제하라. 잃어버릴 염려는 없다. 약속한다.
  • HTML 주석
  • 전역 정보
  • 모호한 관계
    • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
    • 예제 코드

    /*
    * 모든 픽셀을 담을 만큼 충분한 배열로 시작한다(여기에 필터 바이트를 더한다).
    * 그리고 헤더 정보를 위해 200바이트를 더한다.
    */
    this.pngBytes = new byte[((this.width +1) * this.height * 3) + 200];

    • 여기서 필터 바이트란 무엇일까? +1과 관련이 있을까? 아니면 *3과 관련이 있을까? 아니면 둘 다? 한 픽셀이 한 바이트인가? 200을 추가하는 이유는? 주석을 다는 목적은 코드만으로 설명이 부족해서다. 주석 자체가 다시 설명을 요구하니 안타깝기 그지없다.
  • 함수 헤더
    • 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
  • 비공개 코드에서 Javadocs

📗 오늘 읽은 소감

• 이번장을 간단히 정리하자면 "최대한 함수를 통해 주석을 사용하지 않는쪽으로 코드를 작성하고 정말 어쩔 수 없을 때에만 주석을 사용하라"이다. 또한, 소스 코드 관리 시스템이 없었을 때의 주석 습관을 없애고 소스 코드 관리 시스템을 적극 활용하라는 내용도 있었다. 이번 장을 통해 "3장 함수"를 더욱 열심히 공부를 해야겠다는 생각과 소스 코드 관리 시스템인 Git 활용법을 숙달해 내 프로젝트들을 Git으로 잘 관리해야겠다는 생각을 했다.
• 나쁜 주석 파트를 보면서 내가 코드를 작성할 때 정말 쓸때없이 주석을 남용했구나라는 생각을 많이했다. 아직 협업 프로젝트를 진행해본 경험이 많지 않아 주석이 남용되었을 때의 위험성을 인지못했다. 하지만 이번 "4장 주석"을 읽으며 나쁜 주석이 협업할 때 얼마나 위험한지를 자각하게 되었고 협업 프로젝트뿐만 아니라 개인 프로젝트를 진행할 때에도 최대한 주석을 자제하고 꼭 필요한 경우에만 주석을 사용하도록 노력해야겠다.

📙 궁금한 점, 잘 이해되지 않는 점

• javadocs와 같은 API 문서 생성기 패키지가 있듯이 python이나 node js에서는 어떤 모듈 혹은 패키지가 있을까?
  • python : pydoc, sphinx
    • 참고 자료 : https://hooni-playground.com/1101/
  • node js : jsdoc
    • 참고 자료 : https://velog.io/@yijaee/JSDoc%EC%9D%84-%EC%82%AC%EC%9A%A9%ED%95%B4-JavaScript-%ED%8C%8C%EC%9D%BC-%EB%AC%B8%EC%84%9C%ED%99%94%ED%95%98%EA%B8%B0