Каковы некоторые «дзенские» моменты комментирования кода, которые вы создали или просмотрели?

Question

Я ищу примеры достаточно коротких, но достаточно сложных сегментов кода (объектов, функций, классов, определенного набора имен переменных и т. Д.), Которые поражают этот идеальный дзэн, как баланс самодостаточности документации и элегантности реализации.

Это может быть то, чем вы действительно гордитесь, или что-то, что вы встретили и испытали «Ага!». момент просветления.

Некоторые потенциальные критерии (не все должны быть выполнены в одном примере):

• разреженных и Focused
• самоочевидной. Возможно, так ясно написано, что даже программист не мог понять, что вы пытаетесь сделать, даже если они не понимают детали синтаксиса или реализации.
• Явно Полезные (имеет несколько вариантов использования, например, алгоритм сортировки, удобный рекурсивный метод и т.д.)
• Clever
• Просветление
• качества производства и функциональные (например, не псевдо-код)

Я ищу фрагмент примера, за которым следует краткий комментарий о том, что делает код особенным. Конечно, лучшие примеры потребуют минимальных дополнительных комментариев, потому что они хорошо документированы.

Примечание для модераторов: Я новичок в stackoverflow, поэтому, если этот вопрос каким-то образом не подходит или должен быть закрыт, можете ли вы дать объяснение, где он работает в соответствии с нормами stackoverflow? Я не собираюсь тратить время людей.

Цель этого вопроса - изучить хорошие методы комментирования с помощью примеров, представленных и оцененных сообществом.

Answer 1

Рекомендую вам прочитать Beautiful Code. Это отличный пример того, что вам нужно.

Answer 2

Выполнение Джона Бентли Quicksort в C, из книги 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); 
} 

Это просто невероятно. Элегантный, лаконичный, минимальный и исключительно эффективный. В частности, я бы рекомендовал анализ этого алгоритма в главе 3 Beautiful Code. Умопомрачительных!