4장 주석

😃 책에서 기억하고 싶은 내용을 써보세요.

• 잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.
• 우리는 코드로 의도를 표현하지 못해, 그러니 실패를 만회하기 위해 주석을 사용한다.(?)
• 프로그래머들이 주석을 유지, 보수하기란 현실적으로 불가능하다.(?)
• 주석은 나쁜 코드를 보완하지 못한다.
• 주석 말고 코드로 의도를 표현하라.
• 좋은 주석은?
  • copyright
  • 정보를 제공하는 주석(내 생각에는 코드를 읽어서 이해할 수 있다면 이런 주석은 필요 없을 듯 하다.)
  • 의도를 설명하는 주석(역시 내 기준에는 코드를 읽으면 쓴 사람의 의도를 이해할 수 있어야 하고 따라서 이것 역시 불필요한 주석이라 생각한다.)
  • 의미를 명료하게 밝히는 주석(이것 또한 함수나 변수의 의미가 명확하지 않다면 그것 자체가 문제이기 때문에 주석을 다는 것 보다는 의미가 명확하게 나타날 수 있도록 수정하는 것이 좋을 듯 하다.)
  • 결과를 경고하는 주석(책에서 주어진 예시는 '시간이 오래 걸리는 테스트 케이스를 실행할 때 주의하라'라는 주석이었는데 테스트 케이스를 그냥 넘겨짚는 일은 실제 개발에서 이루어지면 큰일난다고 생각한다. 또한 아예 결과를 경고할만한 코드를 짤 일이 없어야 한다.)
  • TODO 주석(개인적으로 TODO주석은 코드를 더럽히는 것 중에 하나라고 생각한다. 꼭 필요한 부분이나 임시로 처리한 부분에만 사용하고, 왠만하면 github 이슈를 사용하는 편이 더 깔끔하다.)
  • 중요성을 강조하는 주석(실행 순서가 정해져 있거나 monkeypatch같이 임포트 순서가 바뀌면 안되는 경우 등 특별한 상황을 제외하고는 역시 코드를 더럽힌다고 생각한다.)
• 나쁜 주석은?
  • 주절거리는 주석
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석(주석은 아니지만 항상 파이썬 개발시에는 펑션마다 의무적으로 docstring을 달았다.)
  • 이력을 기록하는 주석(이건 너무 outdated된 것 같다. 보통 CHANGES.rst에 메인브랜치에 머지된 피알 요약과 함께 따로 관리한다. )
  • 있으나 마나 한 주석
  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라
  • 위치를 표시하는 주석 e.g.// Actions ////////////
  • 닫는 괄호에 다는 주석
  • 공로를 돌리거나 저자 표시하는 주석(이것도 너무 outdated. 이런 주석이 회사 pr에 달렸으면 다들 기절할듯)
  • 주석으로 처리한 코드
  • HTML주석 (2년간 일하며 아직 한 번도 보지 못함.)
  • 전역 정보
  • 너무 많은 정보(보통 자세한 정보는 주석에 담지 않고 api별로 아니면 class 별로 따로 doc파일을 생성한다)

🤔 오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

• 이번 챕터는 나의 의견과는 좀 다르고 오래된 내용들이 많다.
• 평소에 주석은 정말 특이한 케이스가 아니고서는 잘 달지 않는 듯 하다. 타입체크 # type: ignore 정도..?
• 주석은 잘 달지 않지만 docstring은 의무적으로 다는 편이다. 회사 코드는 나 혼자 짜는 것이 아니고 다른 사람이 만든 부분을 내가 수정하는 일도 빈번하기 때문에 어떤 펑션이건 항상 펑션의 간단한 목적과 파라미터, 리턴값을 항상 표기해주고 바뀔 때마다 항상 업데이트 하는 것이 기본이다. vs code에는 자동 docstring 포맷을 생성해주는 툴도 있다.

🔎 궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

• 없음