좋은 코드 주석 쓰기 가이드

(insight.infograb.net)

26P by ironlung 2023-09-14 | favorite | 댓글 8개

코드 주석의 역할:
- 코드 주석은 ‘자신이 작성한 코드가 하는 일’을 설명하는 걸 넘어서 설계 결정 사항과 트레이드 오프 등 고민 사항을 문서화
- 이로써 ‘코드 작성자가 무슨 일을 했고, 왜 그렇게 했는지’ 설명
- 코드 주석은 과거 코드 작성 과정에서 내린 결정의 맥락을 공유하는 데 도움이 됨
- 이는 코드만으로 표현하기 어려운 코드 정보를 전달함
코드 주석의 중요성:
- 복잡한 코드 앞에 달린 인라인 코드 주석은 나중에 코드를 볼 다른 개발자 시간을 절약함
- 프로젝트가 발전할수록 과거에 내린 코드 결정의 맥락을 남겨야 다른 개발자에게 도움됨.
- 코드가 복잡하면 앞에 한 줄짜리 인라인 코드 주석이라도 있어야 함
- 코드만으로 코드 결정의 맥락을 비롯해 다양한 정보를 전달하려면 한계가 있음
좋은 코드 주석 작성법:
1. 간결하게 작성하기
  - 꼭 필요할 때만 필수 정보를 포함하여 주석 쓰기
    - 불가피하게 코드가 복잡할 때
    - 정밀도를 높이기 위해 세부 사항을 추가할 때
    - 맥락이 누락됐을 때(예: 다른 리포지터리 또는 패키지의 코드를 사용할 때)
  - 주석에 혼란과 모호함을 줄이고 유용한 맥락과 정보 제공
2. TODOs/FIXMEs 주석 사용하기
  - TODOs/FIXMEs 주석은 ‘코드의 특정 부분에 작업이 완료되지 않았거나 수정이 필요함’을 나타내는 방법
  - 함수 앞에 “TODO: XX기능을 추가해야 합니다”라는 식으로 작성
  - 코드를 작성하다 '이 부분은 나중에 다시 살펴보아야겠다' 또는 '이 기능은 추후에 개발해야 한다'라는 생각이 들 때 이 방식을 사용하면 관련 사항을 기록하고 추적할 수 있음
  - 활용하면 좋을 Extension: TODO Highlight
3. 주석으로 코드 변명하지 않기
  - 잘못되고 불분명한 코드에 주석을 달며 변명하기보다 코드를 새로 작성하기
  - 어떤 코드는 주석으로 설명해야 하지만, 어떤 코드는 주석에 기대지 않고 ‘코드 그 자체’로 말해야 함
4. AI 활용하기
  - AI 주석 생성기를 사용하면 특정 표준에 따라 일관된 형식으로 주석을 만들 수 있음
  - 전체 프로젝트에서 주석의 일관성을 유지할 수 있어 코드의 가독성 향상
  - 활용하면 좋을 AI 주석 생성기: Readable