I use the following approach to commenting

I use the following approach to commenting:


Each function or method needs a sentence or two that clarifies the following information:


What the routine does


What assumptions the routine makes


What each input parameter is expected to contain


What each output parameter is expected to contain on success and failure


Each possible return value


Each part of the function that isn't completely obvious from the code needs a sentence or two that explains what it's doing.


Any interesting algorithm deserves a complete description.


Any nontrivial bugs you've fixed in the code need to be commented with the bug number and a description of what you fixed.


Well-placed trace statements, assertions, and good naming conventions can also serve as good comments and provide excellent context to the code.


Comment as if you were going to be the one maintaining the code in five years.


If you find yourself saying, "This is a big hack" or "This is really tricky stuff," you probably need to rewrite the function instead of commenting it.
각각의 함수나 메소드들은 다음과 같은 정보를 명백하게 할 수 있는 하나 또는 두개의 문장을 필요로 하게 된다.

루틴이 무엇을 하는가.

루틴이 어떤 가정을 가지고 있는가

각각의 입력 매개변수가 어떤 것을 포함하게 되어 있는가

성공과 실패에 대하여 각각 어떤 출력매개변수가 있는가

가능한 반환값은 각각 무엇인가.

코드에서 완전하게 명백하지 않은 함수의 부분들은 그 부분들이 어떤 것을 하는지 설명할 수 있는 하나 또는 두 개의 문장을 필요로 하게 된다.

모든 중요한 알고리즘은 완전한 설명을 가지고 있어야 한다.

코드에서 고쳐진 사소하지 않은 모든 버그들은 버그 번호와 고친 내용의 설명으로 주석을 달아야 한다.

알맞은 곳에 있는 TRACE,assertion,이름을 잘 명명하는 것 또한 좋은 주석만큼이나 도움이 되고 코드에서 훌륭한 내용을 제공하게 된다.

5년 동안 코드를 유지하게 되는 사람인 것처럼 주석을 단다.

여러분 스스로가 "이거 진짜 속음수인데"라거나 "이건 제대로 구현하는 것이 아닌데"라고 생각되면, 주석을 다는 것보다는 함수를 다시 작성해야 할 것이다.