Introduce

본 내용은 Udemy를 통해 학습한 내용중 기억할 사항들을 정리한 내용들이다.

영어로 주석 제대로 달기

코드 주석

• 코드 주석의 목적 : 이해를 돕는 역할, 코드 수행하면서 머리 속에 정보를 정리 한다.
• 주의
  • 나쁜 코드에 주석을 달지 말고 새로 짜라 - 브라이언 W. 커니핸, P.L. 플라우거
  • 주석은 오래될 수록 코드에서 멀어진다.
• 따라서 잡음은 줄이고 의도는 명확하게 해야 한다. 당연한 것은 배제하고, 정말 필요한 것만을 남겨야 한다.
• 애초에 주석으로 설명할게 아니라 애초에 메소드의 명, 변수 명을 활용하여 주석 대신 설명할 수 있는게 낫다.
• 설명하지 말아야 할 내용
  • 코드만 보면 누구나 알 수 있는 내용
  • 나쁜 함수/ 변수명을 설명하려는 내용
• 설명하면 좋은 내용
  • 코드가 특정 방식으로 작성된 이유
  • 코드에 담긴 결함이나 향후 할 일
  • 어떤 상수가 특정 값으로 정해진 이유
  • 평범한 사람이 예상치 못한 특이한 동작
  • 파일/클래스 수준에서 큰 그림을 설명하는 주석

코드 문서화

• Javadocs 와 같은 코드 문서화 도구에서 주의사항
  • 형태가 갖춰져 있다
    • 중복된 내용들이 있을 가능성 있음
    • 그릇된 정보를 제공할 가능성도 있다.
  • 공개 API 에 대해서만 작성
    • 시스템 내부에 속한 클래스와 함수는 쓰지 말자
    • 유용하지 않고 코드만 지저분해지는 문제점을 막기 위해서다.
• 주석과 관련된 스타일 가이드
  • 3인칭으로 작성할 것
    • Gets the label(preferred)
    • Get the label(X)
  • 메소드 설명은 동사구로 시작한다.
    • Gets the label of this button.(preferred)
  • 클래스, 인터페이스, 필드는 주어 생략
    • A button label(preferred)
    • This field is a button label(avoid)
  • 현재 클래스에서 생성된 객체를 지칭할 때는 the 대신 this 사용할 것
    • Gets the toolkit for this component(preferred)
    • Gets the toolkit for the component(avoid)
• doxygen 소개
  • C++ 소스 코드용으로 문서를 만들어내는 도구
  • 지원 언어는 점점 확장됨
  • 특징
    • HTML, LaTex을 생성
    • 의존성 그래프, 상속 다이어그램과 같은 코드의 구조화된 모양새를 표현
    • 사용자 메뉴얼이나 웹 사이트와 같은 일반 문서 생성(코드를 사용한 문서화)
    • 멀티 플랫폼 지원

간단 정리

• 코드 주석은 코드의 how 를 설명하는 대신
  • 핵심 요약이나
  • why 나
  • 배경 맥락을 설명해야한다.
• 코드 문서화는 내부 동작 방식이 아니라
  • 파일이나 클래스 수준 주석에서 큰 그림을 설명한다.
    • 외부 공개 클래스
    • 외부 공개 메소드
    • 외부 공개 상수