26P by ironlung 13일전 | favorite | 댓글 8개
  • 코드 주석의 역할:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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