本当に良いコメントは

あなたは何もせずにできました。

おじさんボブ

最近、コードにコメントするかどうかについての活発な議論が非常に疲れてきました。原則として、バリケードの片側には、 「しかし、コメントなしでは理解できないので、どうして私はコメントできないのか」というフォームの議論の余地のない立場を持っている自信のある後輩がいます。他の-経験の賢明な先輩。彼らは、コメントなしでそれができるなら、 「そうするのが良いだろう 、それを気にすることだ！」と理解しています 。おそらく、多くの人は学生のベンチからのコメントを渇望しており、仲間の教師が各行にコメントを強制し、 「学生がよりよく理解できるように」しています 。実際のプロジェクトでは、コードを詰まらせるだけのコメントはたくさんありません。ただし、コメントをまったく記述しないことは推奨しませんが、説明を必要としないコードを記述できた場合は、これを小さな勝利と見なしてください。私はすぐにいくつかの非常に賢い本を参照したいと思いますが、それに基づいて私の立場が形成されました。私はこれらの作品の著者を愛し尊敬し、彼らの意見を完全に共有しています。

では、何が私をコメントにいらいらさせますか？基本的なポイントをいくつか挙げます。

コメントはすぐにコードを乱雑にし、読みやすさを損ないます
コメントの作成とサポートには時間がかかります
コメントがあります（曲がって書かれたものから始まり、古いもので終わります）

原則として、コメントが必要な場合があることに同意します。しかし、そのようなケースが少ないほど、コードはより美しくなります。さらに、良い解説を書くことも芸術です。残念ながら、多くのプログラマーがそれを持っているわけではなく、ほとんどの人はとにかくコメントを書きます。これの利点はしばしば疑わしいです。そして、有能なコメントを書くために時間と労力を費やす方法は、コメントを必要としないようにコードを書き換えるためにお金を費やす方が良いのではないでしょうか？

コメントの必要性について具体的なことを言うことができるいくつかの典型的なシナリオを議論しましょう。 C＃でコードの例を示しますが、このトピックではこれは重要ではありません。

コメントなしでできるとき

コードを繰り返すコメント

コードを見てみましょう。

//        
public int CalcSumOfElement(int[] elements) //      
{
  int result = 0; //     
  int n = elements.Length; //   , ..  
  for (int i = 0; i < n; i++) //     
    result += elements[i]; //     
  return result; //  
}

, , , , , . . — . . : . , — .

,

, :

public class Item
{
  private int value; //   ,    

  //  
  public Item(int twoValue)
  {
    value = twoValue >> 1; //       
    //       
  }
}

, . , , . , .

,

HashSet<int> set; //   ,   -
//     
//     ,        
//   -    : http://ru.wikipedia.org/wiki/%D0%A5%D0%B5%D1%88-%D1%82%D0%B0%D0%B1%D0%BB%D0%B8%D1%86%D0%B0

- , / / . . .

,

//    
// public void DoIt()

, ///. , . - , , . ! - - ?

,

: «, 300 , . . 10- , ». , , , - . 300- . — .

,

public int GetSeconds(int hours)
{
  return hours * 3600; // 3600 -   ,  
}

, , — , , . , . , :

private const int SecondsInHour = 3600;
public int GetSeconds(int hours)
{
  return hours * SecondsInHour;
}

,

« » , .

MOV AX, 723h ; R. I. P. L. V. .

, : «Rest in peace, Ludwig van Beethoven», .. 723 — .

, , . ( ), - ( « , , »). , . , - .

,

, , . .

public void Main()
{
  // ,    .
  //      .
  //      Run.
  //   , Run  «».
  //      ,   .
  //    ,   .
  //     ,         Main.
  //      ,    Main.
}

,

, , . , , .

// Sum(1, 2) == 3
// Sum(2, 1) == 3
// Sum(2, 2) == 4
public int Sum(int a, int b)

— . , Unit-. . Unit- — . - , Unit-?

,

, , :

// 11.06.13:    .    - -,    .
// 12.06.13: ,   —   .   .

: — . . , . - , .

,

. , , - . :

// int number = GetNumber()
// int number = 4;
// int number = 5;
int number = 4;
// double number = 4.5;
// decimal number = 4.5;
// string number = " ";

? : , , . , — . , . , . , , : « , , , , ».

,

bool flagA = true;
bool flagB = false;
bool flagC = true;
if (Condition(flagA, flagB, flagC))
  Foo();
// else   true,

. true? true else- , true. , ? ?

, . , . ! , , .

,

. , . . , , , - ASCII-, , . , .

, . , (, ).

,

//   
public int Sum(int a, int b)

. ? , - , , . : , . , . , , , .

,

, , , . - . , , .

,

, , . , . , - , . , , «» . , , . , .

, TODO

- . , IssueTacker, . , Issue, , , . , IDE TODO- , . , . TODO- , .

,

- , , . , , . , , - , . , .. , . , - , — , .

,

( ). , , . API, private- . , . , , .

,

- , .. , — , .

: , , — , . , , — , , . , , , . , — , - .

Update:

, , , , . , ( , , ..). , , (, ). , 100 , , . , . , : — , , . — .

コメントするかコメントしないか？

コメントなしでできるとき

コードを繰り返すコメント

,

,

,

,

,

,

,

,

,

,

,

,

,

,

,

, TODO

,

,

,

More articles: