Clean Code 4장 주석

 

 

 

#1. 주석은 나쁜 코드를 보완하지 못한다.

• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
• 주석으로 설명하려 애쓰지 말고 그 시간에 코드를 더욱 분명하게 짜는 것이 좋다.

#2. 좋은 주석의 종류

• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
• 결과를 경고하는 주석
• TODO 주석
• 중요성을 강조하는 주석
• 위의 주석들은 그래도 좋은 주석이라 칭하지만 그래도 주석을 달지 않고 더 좋게 나타낼 수는 없는지 고민하고 주석을 사용하더라도 올바른 사용을 해야 한다. 잘못된 주석 사용은 사용하지 않은 것보다 더 잘못된 정보를 줄 수 있다.

#3. 나쁜 주석의 종류

• 주절거리는 주석
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석
• 이력을 기록하는 주석 (예전에는 소스 코드 관리 시스템이 없었으니까 첫머리에 변경 이력을 기록하는 관례가 바람직했지만 지금은 혼란만 가중할 뿐이다. 사용하지 말자!!!!!!)
• 있으나 마나 한 주석 
• 위치를 표시하는 주석
• 공로를 돌리거나 저자를 표시하는 주석 (이것 역시 위의 주석과 마찬가지로 소스 코드 관리 시스템을 사용하는 것이 바람직하다.)
• 주석으로 처리한 코드 (주석으로 처리된 코드는 이유가 있어서 남겨놓은 지 알기 때문에 다른 사람이 지우기를 주저한다. 사용하지 말자!!!!!)
• HTML 주석
• 전역 정보 (주석을 달아야 한다면 그 근처에 있는 코드에만 기술하는 것이 맞다.)
• 대다수의 주석이 나쁜 주석의 범주에 속한다.

 

느낀 점

이번 장을 보면서 느낀 것을 정리해 보면 "주석이 코드보다 더 많은 정보를 제공하지 못한다.",  "잘못된 주석은 오히려 코드를 복잡하게 만들며, 혼동과 무질서를 초래한다." 이 정도로 정리할 수 있을 것 같다. 지금까지는 주석을 단지 다른 사람들에게 추가 정보를 제공해 주는 정도로 생각했고, 내 주석이 혼란을 가중시킬 것이라는 생각은 하지 않았다. 이 점을 기억하며 가능하면 주석을 사용하지 않고 주석 사용보다는 함수 이름과 함수 코드를 더 잘 짤 수 있는 방법에 시간을 더 써야겠다는 생각이 들었다.