Writing Effective Comments for Readability and Maintainability

클래스, 함수, 변수 등에 주석을 잘 다는 것은 코드의 가독성과 유지보수성을 높이는데 많은 도움이 된다.

High Quality Code 를 작성하기 위한 노력과 관심을 지속적으로 갖지 않은 상태에서, 어느 정도 연차가 쌓이면 보통 자신만의 코딩 습관이 생긴다. 문제는 이 습관이 가독성과 코드를 이해하는데 어려움을 주어서 코드 리뷰나, 협업 관점에서 시간을 잡아먹는 경우가 있다.

많은 정책이 결합된 복잡한 비지니스 로직을 작성하는 경우에 High Quality Code 를 작성하기는 더 어려워진다. 여러 가지 정책과 조건이 얽힌 복잡한 로직을 작성하다 보면, 코드의 가독성뿐만 아니라 유지보수성도 중요한 문제가 된다. 추상화의 수준이 높아지면서, 각 정책이나 비즈니스 규칙이 코드 곳곳에 분산되기 때문에 이러한 로직을 쉽게 이해하고 수정하기가 어려워진다.

추상화 수준이 높을수록 코드는 세분화되고, 복잡해지며, 이를 관리하는 일이 힘들어집니다. 각 기능이나 정책이 잘 분리되지 않으면, 정책의 변경이 있을 때마다 많은 코드 수정이 필요하고, 이는 또 다른 버그를 유발할 수 있습니다. 또한, 코드가 점점 더 길어지고 복잡해지면, 테스트나 디버깅도 더 어려워지고, 코드 리뷰 과정에서 피드백을 주고받는 데 더 많은 시간이 소요된다.

이러한 관점에서 주석은 코드를 이해하고 유지보수 하는데 도움을 준다.

  • 주석은 이름보다 훨씬 더 많은 정보를 담을 수 있다.
  • 주석은 클래스, 함수 등의 역할을 설명한다. (what, why, how)
  • 주석은 코드의 논리를 명확하고 빠르게 이해하는데 도움을 준다.
  • 주석은 코드 처럼 관리의 대상이다. 따라서 코드의 논리가 수정되었을때 주석이 수정되지 않는다면 코드와 주석의 불일치가 생겨서 컨텍스틀 파악하는데 더 많은 시간을 들여야할 수 있다.

Anti-Patterns:

  • 코드를 사용하는 쪽을 언급하는 경우에는 불필요하게 강한 의존 관계를 만들 수 있다.
  • 구현의 세부 사항을 언급하는 경우에는 주석의 내용이 세부 사항 정보에 의존하게 된다.

문서화를 위한 주석을 작성하는 경우:

  • 함수, 클래스가 무엇을 하는지에 대해 역할을 간결하게 설명한다.
  • 코드보다 더 높은 수준의 추상도와 세밀함을 유지한다.
  • 구현의 세부사항이나 코드를 사용하는 쪽을 언급하지 않는다.

주석에 너무 많은 정보를 담아야 하는 경우에는 코드에 Jira Ticket 과 같은 이슈 관리 시스템의 티켓 정보를 담은 주석을 작성할 수도 있다. 특정 로직을 작성함에 있어서, 특별한 이유가 있는 경우(다른 팀원들이 잘 못 수정하지 않게 하기 위해서) 그 이유를 주석으로 작성할 수 있다.

References

  • 읽기 쉽고 코드 리뷰하기 좋은 코드 작성 가이드 LINE / 이시가와 무네토시
  • 设计模式之美 / 王争