좋은 코드 주석 쓰기 가이드

• 코드 주석의 역할:

  • 코드 주석은 ‘자신이 작성한 코드가 하는 일’을 설명하는 걸 넘어서 설계 결정 사항과 트레이드 오프 등 고민 사항을 문서화
  • 이로써 ‘코드 작성자가 무슨 일을 했고, 왜 그렇게 했는지’ 설명
  • 코드 주석은 과거 코드 작성 과정에서 내린 결정의 맥락을 공유하는 데 도움이 됨
  • 이는 코드만으로 표현하기 어려운 코드 정보를 전달함

• 코드 주석의 중요성:

  • 복잡한 코드 앞에 달린 인라인 코드 주석은 나중에 코드를 볼 다른 개발자 시간을 절약함
  • 프로젝트가 발전할수록 과거에 내린 코드 결정의 맥락을 남겨야 다른 개발자에게 도움됨.
  • 코드가 복잡하면 앞에 한 줄짜리 인라인 코드 주석이라도 있어야 함
  • 코드만으로 코드 결정의 맥락을 비롯해 다양한 정보를 전달하려면 한계가 있음

• 좋은 코드 주석 작성법:

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

[penza1]

주석이 필요해 보이면
코드가 잘못 된건 아닌가 고민해 보는건 어떨까 합니다

코드와 생명,기능을 함께하지 않는 주석은 미래에 그 주석을 보게될 개발자나 나 자신에게 혼선을 줄수도 있어요

과거의 맥락이 현재와 무관하거나 오류를 발생시켰음에도
그 과거의 맥락 문장으로 현재의 수정을 주저하게 되거나 다른 구조로 하결하려 우회하게되고
실수를 더 유발 시킬수도 있고..

경험상 그땐 맞았으나 지금 틀린 이유를 알수 있는 주석은 그리 많지 않아서....

[ironlung]

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

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

이걸 보면서 또 주석을 지나치게 쓰지 않으려 노력도 합니다

[ironlung]

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

[iamchanii]

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

[ironlung]

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

[balak]

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

[ironlung]

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