作成またはレビューしたコードコメントの「禅」の瞬間は何ですか？

Question

私は合理的に短いですが、かなり複雑なコードの例（オブジェクト、関数、クラス、特定の変数名のセットなど）を探しています。

あなたが本当に誇りに思っているか、あなたが出会って「Aha！啓蒙の瞬間

いくつかの潜在的な基準は、（すべてではないが、単一の例では満たす必要がある）：

• スパースと明らか
• 自己を重視しました。文法や実装の詳細を理解していなくても、非プログラマであっても、あなたがやろうとしていることを理解することができます。
• 賢い
• 啓発
• 生産品質及び機能（例えばない擬似コード）

（複数のユースケース、例えばソートアルゴリズム、便利な再帰的方法、等を有している）明らかに有用私はコードスニペットの後に、コードを特別なものにする簡単な解説を探しています。もちろん、最良の例は、十分に文書化されているため、最小の追加解説を必要とします。

司会者への注意：私はstackoverflowを初めて使ったので、この質問が何らかの形で適切ではない、あるいは閉じなければならない場合は、stackoverflowの標準とどこで違反しているのかを説明できますか？私は人々の時間を浪費するつもりはない。

この質問の目的は、コミュニティによって提供され評価された例を通じ、良いコメント行為を学ぶことです。

Answer 1

私はあなたがBeautiful Codeを読むことをお勧めします。それはあなたが何をしているかの素晴らしい例です。

Answer 2

QuicksortのCでの実装、Programming PearlsからのJon Bentleyの実装。

void quicksort(int l, int u) { 
    int i, m; 
    if (l >= u) return; 
    swap(l, randint(l,u)); 
    m = l; 
    for (i=l+1; i<=u; i++) 
     if (x[i] < x[l]) 
      swap(++m, i); 
    swap(l, m); 
    quicksort(l, m-1); 
    quicksort(m+1, u); 
} 

それだけで信じられないほどです。エレガントで簡潔で、最小限で、効率的です。特に、私はBeautiful Codeの第3章のこのアルゴリズムの分析をお勧めします。マインドブロー！