주석에 대하여
- … 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요없는 방향으로 에너지를 쏟겠다.
- 주석은 나쁜코드를 보완하지 못한다.
- 코드로 의도 표현
- 주석으로 말하려는 의사를 함수로 만들어서 표현하는것으로도 충분하다.
- 좋은 주석
- 애초에 좋은 주석이란 없다. 하지만 불가피하게 작성해야하는 경우를 설명한다.
- 법적인 주석, 의미를 명료하게 밝히는 주석, 결과를 경고하는 주석, TODO, 중요성을 강조하는 주석
- 외에 정보를 제공하거나 의도를 설명하는 주석은 좋지만 함수나 변수로 대체할 수 있다면 대체하는 것이 좋다. 하지만 때때로 주석으로 의도를 설명하는것이 더 낳을 때도 있다.
- 여러 코드를 나누는 주석도 나쁘지 않다.
- 예시:
TODO:를 사용해서 일시적인 코드를 지워야 함을 주석으로 남겨두었다.
- 예시: 다양한 endpoint를 주석으로 구분해두었다.
- 나쁜 주석
- 목적성이 모호하거나 읽는 사람에게 잘못된 정보를 전달하거나 함수로 대체할 수 있거나 중복 되거나 함수가 너무 길어서 단 주석의 경우가 나쁜 주석이 될 수 있다.
주석에 너무 많은 정보를 담거나 연관되지 않은 정보를 주석에 담는것도 나쁘다.
- 예시: 함수 이름을 수정해주면 주석이 필요 없다.
- 예시: 주석으로 남겨진 코드
- 정리
되도록이면 주석은 함수나 변수로 대체하는 것이 좋으며 주석을 달지 않아도 이해할 수 있도록 네이밍과 가독성에 신경을 써야한다.
또한, 주석이 꼭 필요한 경우인지를 생각하고 주석을 없앨 수 있는 방안을 모색해보는 것이 좋다. 주석을 달아야한다는 생각보다 코드를 정리하는 것이 좋다.
