주석에 담아야 하는 대상
더스틴 보즈웰, 트레버 파우커
느낌표 ! (인상 깊은 문장 | 문맥)
코드에서 빠르게 유추할 수 있는 내용은 주석으로 달지 말라.
p.78
필자는 주석을 거의 사용하지 않는데 대부분 이러한 이유였다. 그렇지만 외부인의 입장에서는 큰 틀에서 빠르게 유추할 수 없을 것이기 때문에 주석에 관하여 생각을 다시하게 한다.
나쁜 이름에 주석을 달지 마라 - 대신 이름을 고쳐라
p.79
저자도 말하듯 좋은 코드에는 주석이 필요없다. 변수명 함수명을 잘 지으면 어떠한 역할과 기능을 하고 있는지 설명할 필요가 없기 때문이다. 변수명을 잘 짓기는 항상 어렵다..
주석으로 코드가 왜 훌륭하지 않은지도 설명할 수 있다.
// 이 클래스는 점점 엉망이 되어가고 있다. 어쩌면 'ResourceNode' 하위클래스를 만들어서 정리해야 할지도 모르겠다.이 주석은 코드가 엉망이라는 사실을 밝히고 다음 사람에게 어떻게 수정해야 하는지 알려준다. 만약 이 주석이 없으면 많은 사람이 이 코드에 겁을 먹어 건드리지 않으려고 할 것이다.
p.81
주석은 잘 작성된 코드에만 작성해야한다고 생각을 했었는데 저자는 지금 상황에서 안 좋은 코드가 있을 수 있고 그것을 그냥 넘어가서는 안된다고 말하고있다. 생각을 해보면 오히려 잘못된 코드일수록 주석을 달아야하는데 숨기고 싶은 마음에 주석을 작성 안하는 것은 오히려 더 안 좋은 코드로 만드는 것인 것 같다. 약점은 약점으로 받아들일 수 있어야하는 것처럼 정직하게 주석을 달아야할 것이다. 그 코드를 작성한 내가 가장 잘 알 것이기 때문이다.
표시 (p.82)
| 표시 | 보통의 의미 |
|---|---|
| TODO: | 아직 하지 않은 일 |
| FIXME: | 오동작을 일으킨다고 알려진 코드 |
| HACK: | 아름답지 않은 해결책 |
| XXX: | 위험! 여기 큰 문제가 있다 |
| TextMate | ESC |
TODO 만 알고있었는데 다른 표시도 유용할 것 같다.
def GenerateUserReport(): # 이 사용자를 위한 lock 을 얻는다. ... # 데이터베이스에서 사용자의 정보를 읽는다. ... # 정보를 파일에 작성한다. ... # 사용자를 위한 lock 을 되돌려 넣는다.이러한 주석을 함수가 수행하는 기능의 글머리 요약 역할을 수행하므로, 코드를 읽는 사람은 자세한 내용을 읽기 전에 주석을 보고 요점을 파악할 수 있다.
p.88
위와 같은 코드가 필요하다면 필자는 들여쓰기로 기능별로 표현하려고하지만 주석을 달 생각은 하지 못했다. 저자가 예시를 든 상황 같은 경우는 주석이 매우 적절해보인다. 주석이 없다면 좋은 변수명과 함수명이라고해도 시간이 더 걸렸을 것이고 이해가 부족했을 수 있을 것 같다. 이 책이 너무 좋은 이유는 예시가 너무 와닿게 되어있다는 것이다. 적절한 예시를 얻기 위해 어떻게보면 좋지 않은 코드도 수도 없이 봐왔다는 것을 유추해볼 수 있다. 항상 좋은 것만 봐서는 진짜 좋은 것이 뭔지 모르듯 안 좋은 상황에서 좋은 상황을 바꿀 수 있는 개발자가 되고 싶다.
앞으로 주석 달기를 주저하게 된다면 머릿속에 떠오르는 생각을, 심지어 다듬어지지 않은 생각이라고 해도 일단 쓰기 시작하라.
p.89
주석을 안 달게되는 이유는 주저하게 되는 것이 큰데 좋은 주석을 작성하도록 노력해봐야겠다. 주석을 작성하기 위해서는 현재 기능이 무엇이고 어떠한 기능을 수행해서 어떤 변화와 어떤 값을 반환하는지 또 추후 어떤게 추가되어야하고 어떤게 분리가 되어야하는지 등 고려해야하기 때문이다. 저자도 지적하듯 설명을 위한 설명은 필요없지만 적절한 주석은 코드의 관리성을 높이는 것 같다.
Chapter 5 느낌
Chapter 5 에서는 좋은 주석에 예시를 주면서 막연하게 주석 달기를 시작해보라고 권하고있다.