# 좋은 코드 주석 쓰기 가이드

> Clean Markdown view of GeekNews topic #10867. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=10867](https://news.hada.io/topic?id=10867)
- GeekNews Markdown: [https://news.hada.io/topic/10867.md](https://news.hada.io/topic/10867.md)
- Type: news
- Author: [ironlung](https://news.hada.io/@ironlung)
- Published: 2023-09-14T10:09:45+09:00
- Updated: 2023-09-14T10:09:45+09:00
- Original source: [insight.infograb.net](https://insight.infograb.net/blog/2023/08/16/good-code-annotation)
- Points: 26
- Comments: 8

## Topic Body

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

## Comments



### Comment 19333

- Author: penza1
- Created: 2023-09-19T12:19:33+09:00
- Points: 2

주석이 필요해 보이면  
코드가 잘못 된건 아닌가 고민해 보는건 어떨까 합니다  
  
코드와 생명,기능을 함께하지 않는 주석은 미래에 그 주석을 보게될 개발자나 나 자신에게 혼선을 줄수도 있어요  
  
과거의 맥락이 현재와 무관하거나 오류를 발생시켰음에도  
그 과거의 맥락 문장으로 현재의 수정을 주저하게 되거나 다른 구조로 하결하려 우회하게되고  
실수를 더 유발 시킬수도 있고..  
  
경험상 그땐 맞았으나 지금 틀린 이유를 알수 있는 주석은 그리 많지 않아서....

### Comment 19341

- Author: ironlung
- Created: 2023-09-19T16:19:15+09:00
- Points: 1
- Parent comment: 19333
- Depth: 1

귀한 의견 공유해주셔서 감사합니다. 나눠주신 의견을 생각해보니 코드 발전을 위해서도 주석 필요성을 꼼꼼히 되묻는 노력도 필요하다 싶어요. :)

### Comment 19310

- Author: aqqnucs
- Created: 2023-09-18T18:52:22+09:00
- Points: 2

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq  
  
이걸 보면서 또 주석을 지나치게 쓰지 않으려 노력도 합니다

### Comment 19311

- Author: ironlung
- Created: 2023-09-18T19:19:31+09:00
- Points: 1
- Parent comment: 19310
- Depth: 1

좋은 영상 공유해주셔서 감사합니다! :)

### Comment 19219

- Author: iamchanii
- Created: 2023-09-15T12:28:06+09:00
- Points: 1

아무리 도로가 잘 닦여져 있다고 해도 이정표는 꼭 필요하다고 생각합니다. 그래서 요즘은 주석 쓰기를 습관화 해보려고 노력하고 있습니다.

### Comment 19228

- Author: ironlung
- Created: 2023-09-15T13:02:42+09:00
- Points: 1
- Parent comment: 19219
- Depth: 1

댓글로 인사이트 나눠주셔서 감사합니다. 말씀주신 내용을 생각해보니 주석도 중요한 테크니컬 라이팅이라 라이팅 기본 원칙을 다시 돌아보게 됩니다. :)

### Comment 19215

- Author: balak
- Created: 2023-09-15T11:39:03+09:00
- Points: 1

코멘트가 없어도 이해되게 코드를 작성하는 게 최선인거 같아요

### Comment 19227

- Author: ironlung
- Created: 2023-09-15T13:01:16+09:00
- Points: 1
- Parent comment: 19215
- Depth: 1

넵, 기본에 충실한 게 우선이라는 생각이 들어요. 댓글 감사합니다. :)