comment-conventions - 您创建或查看过哪些“禅宗”代码评论时刻？

Question

我正在寻找相当短但相当复杂的代码段（对象、函数、类、一组特定的变量名等）的示例，它们可以达到完美的禅意，就像自我文档和实现优雅的平衡一样。

它可能是您真正引以为豪的事情，也可能是您遇到并经历过“啊哈！”的事情。顿悟的时刻。

一些潜在标准（并非所有标准都需要在一个示例中满足）：

• 稀疏而集中
• 不言自明。也许写得这么清楚，即使是非程序员也能理解你想要做什么，即使他们不理解语法或实现细节。
• 明显有用（有多个用例，例如排序算法、方便的递归方法等）
• 聪明的
• 启蒙
• 生产质量和功能（例如不是伪代码）

我正在寻找一个示例片段，然后是对代码特别之处的简短评论。当然，最好的示例将需要最少的额外评论，因为它们有据可查。

版主注意：我是stackoverflow的新手，所以如果这个问题不合适或必须关闭，你能解释一下它在哪里违反了stackoverflow的规范吗？我不打算浪费人们的时间。

这个问题的目标是通过社区提供和评价的示例来学习良好的评论实践。

Answer 1

Jon Bentley 用 C 语言实现的Quicksort，来自Programming Pearls书。

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 章中对该算法的分析。令人兴奋！

Answer 2

我推荐你阅读Beautiful Code。这是你所追求的一个很好的例子。