[번역] 13 Tips to Comment Your Code

13 Tips to Comment Your Code
1.Comment each level
각 레벨에 대해 각 코드 블록을 통일된 방법으로 주석합니다(예:
n은 각 클래스에 대한 간단한 설명, 작성자 및 최종 수정 날짜를 포함합니다.
n각각의 방법, 목적, 기능, 매개 변수, 반환값 포함
팀 프로그래밍을 할 때 표준적인 주석을 채택하는 것이 매우 중요하다.물론 코드 협정과 도구(예를 들어 c#의 XML과 자바의 자바doc)를 사용해서 이 일을 돕는 것도 받아들일 수 있고 심지어 더 취할 수 있다.
2.Use paragraph comments
코드 블록을 여러 세션으로 나누고, 각 세션은 간단한 작업을 수행한 다음, 각 세션 앞에 주석을 추가하여 독자가 곧 무슨 일이 일어날지 유도한다.// Check that all data records // are correct foreach (Record record in records) {     if (rec.checkStatus()==Status.OK)     {         . . .     } } // Now we begin to perform // transactions Context ctx = new ApplicationContext(); ctx.BeginTransaction(); . . .
3.Align comments in consecutive lines
여러 줄이 있고 줄마다 주석이 뒤따르는 경우, 우리는 이 주석들을 배열해서 그것들이 더욱 쉽게 읽을 수 있도록 해야 한다.const MAX_ITEMS = 10; // maximum number of packets const MASK = 0x1F;    // mask bit TCP       Tab ， 。 ， IDE ，tab 。 4.Don’t insult the reader’s intelligence     ， ：     if (a == 5)      // if a equals 5         counter = 0; // set the counter to zero       ， ， 。 5.Be polite     ， "Notice the stupid user has entered a negative number"또는 "This fixes the side effect produced by the pathetically inept implementation of the initial developer.이런 주석은 그들의 프로그램 코드에서 좋은 효과를 얻기 어려울 뿐만 아니라, 앞으로 누가 이런 주석을 읽을지, 당신의 상사, 고객, 또는 불쌍한 어리석은 초보자도 모른다.
6.Get to the point
네가 뜻을 전달하는 것과 무관한 주석을 쓰지 마라.우스갯소리, 시와 군말을 피하다.간단히 말하면, 주석을 간결하고 직접적으로 유지한다.
7.Use a consistent style
어떤 사람들은 주석을 써서 비프로그래머도 이해할 수 있도록 해야 한다고 생각하고, 다른 사람들은 프로그래머에게만 하면 된다고 생각한다.어쨌든 성공적인 코드 주석 전략으로서 일치하고 항상 같은 독자를 대상으로 해야 한다.개인적인 의견으로는, 나는 심지어 많은 비프로그래머들이 코드를 읽을 수 있을지 의심하기 때문에, 주석은 프로그래머를 대상으로 해야 한다.
8.Use special tags for internal use
팀을 개발할 때, 일치하는 라벨을 프로그래머 간의 소통으로 채택한다.예를 들어, 많은 팀이 추가 작성이 필요한 코드 세그먼트를 나타내기 위해 "TODO:"탭을 사용합니다.int Estimate(int x, int y) {     // TODO: implement the calculations     return 0; } ， 。 ， ， 。 9.Comment code while writing it     ， 。 ， 。“I have no time to comment“，”I’m in a hurry” “the project is delayed” 。 。 ： public void ProcessOrder()   {     // Make sure the products are available     // Check that the customer is valid     // Send the order to the store     // Generate bill } 10.Write comments as if they were for you(in fact,they are)     ， ， 。
위대한 Phil Hack은 "As soon as a line of code is laid on the screen, you're in maintenance mode on that piece of code.
결과적으로 우리 스스로가 우수한 주석의 첫 번째 수혜자가 될 것이다.
11.Update comments when you update the code
만약 주석이 코드에 따라 업데이트되지 않았다면, 그런 주석은 정확함을 보장할 수 없을 것이다.코드와 주석은 반드시 동시 수정해야 한다. 그렇지 않으면 코드를 유지하는 개발자의 업무를 어렵게 할 것이다.특히 재구성 도구가 자동으로 코드를 업데이트하고 주석을 바꾸지 않은 경우에도 같은 결과를 초래할 수 있으니 주의해야 한다.
12.The golden role of comment:readable code
프로그래머의 기본 기능 중 하나: 코드를 자신을 위해 말하게 하는 것이다.비록 일부 주석을 쓰는 것을 좋아하지 않는 사람들은 이것이 프로그래머들이 멋대로 지어낸 것이라고 의심하지만, 사실은 자명한 코드가 더 쉽게 이해할 수 있는 코드를 작성하고 심지어는 주석을 불필요하게 만드는 데 좋은 도움이 된다는 것이다.예를 들어, Fluid Interfaces 기사에서 보여준 깨끗하고 자명한 코드는 다음과 같습니다.Calculator calc = new Calculator(); calc.Set(0); calc.Add(10); calc.Multiply(2); calc.Subtract(4); Console.WriteLine( "Result: {0}", calc.Get() );
이 예에서 주석은 필요 없고 그렇게 하면 4조와 어긋날 수도 있다.더 쉽게 읽을 수 있는 코드를 작성하려면 적절한 이름 지정 방법(Stringer's Rules)을 사용하여 정확한 축소 및 코드 스타일 가이드를 사용해야 할 수도 있습니다.이 힌트를 지키지 않은 결과는 주석이 엉터리 코드에 사과하는 것처럼 보였을 수도 있다.
13.Share these tips with your colleagues
비록 우리가 10조에서 우리 스스로가 어떻게 우수한 주석으로부터 즉각적으로 이익을 얻었는지 지적했지만, 이러한 조항들은 모든 개발자, 특히 팀 개발에 유용하다.따라서 이 주석 조항들을 동료와 공유하고 알기 쉽고 유지하기 쉬운 코드를 함께 쓰십시오.