Только самые красивые модули могут сделать это самостоятельно.

Какой-то код красивый.

Некоторый код просто замечательно читать. Понятно, что имел в виду автор. Вам не нужно погружаться на уровни абстракции, чтобы понять, что происходит. Именование ясное, поток управления удобочитаемый, и вы больше чувствуете, что читаете историю, чем набор связанных математических утверждений.

По моему опыту инженера-программиста, этот код встречается редко. Он, как правило, многократно уточняется в течение нескольких лет, вероятно, с участием нескольких авторов.

Я думаю, вы можете привести веские доводы (и я это делаю), что этот код не нуждается в комментариях. Мало того, что организация кода логична и понятно, что он делает, но из-за того, как он написан, понятна и намерение. Абстракции, выбранные авторами, просто кажутся правильными, и ясно, какие проблемы они решают с каждым решением. Трудно думать, как поступить иначе.

средний Джо

Большинство кодов не такие.

Даже код, который в конечном итоге попадает туда, обычно не начинается таким образом. В отличие от книг, где мы видим только готовый продукт, программное обеспечение — это живая дышащая вещь, которая постоянно модифицируется и улучшается (или деградирует).

Что касается кода, который я читал, то я бы сказал, что среднийкод довольно прилично объясняет, что он делает сам по себе. Где он терпит неудачу, так это в описании почему. Почему были приняты определенные проектные решения, что означает вход в конкретную ветвь или каково значение возврата нулевого значения. Чего автор пытается добиться с помощью своего кода.

И тут на помощь приходят комментарии.

Хуже чтения плохого кода с комментариями может быть только чтение плохого кода безкомментариев.

Комментарии, сообщающие о намерениях в трудночитаемом коде, являются спасательным кругом. «Ааа, так вот почему автор выбрал именно этот алгоритм и назвал этот набор функций. Они пытаются сделать X.”

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

А ты?

Теперь, как вы думаете, где вы окажетесь в спектре от некомпетентного дурака до среднего джоуна и мастера мирового класса? Если бы мне пришлось угадать, если вы читаете это, вы, по крайней мере, в середине пакета. Но всегда ли вы производите безупречный код?

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

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

Поэтому пишите комментарии, чтобы сообщить о своих намерениях.

Сколько и где?

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

Но, пожалуйста, не переусердствуйте. Не будь этим человеком:

# Setting up the module
setup()

Этот человек делает немного лучше со своим комментарием:

# Prepare the device to handle incoming tcp connections
setup()
do_stuff()
do_other_stuff()
socket = open_socket()
if not socket:
  raise Exception('Device is not ready for reading')

… но чего-то все равно не хватает. Комментарий сообщает, что делается, а не почему это делается. Это полезно, но не так полезно, как могло бы быть. Этот тип комментария можно преобразовать в функцию, и вы можете добавить еще более полезный комментарий в эту функцию ниже:

def prepare_device_for_tcp():
    # device is often unreliable and needs substantial babying
    setup()
    do_stuff()
    do_other_stuff()

prepare_device_for_tcp()
socket = open_socket()
if not socket:
    raise Exception('device is not ready for reading')

Не могли бы вы сообщить, что вы ожидаете, что устройство будет ненадежным через сам код? Не совсем. Явное добавление повторных попыток для различных методов указывает на то, что вы ожидаете, что они потерпят неудачу, но это все равно требует скачка вывода, который не каждый сделает.

Заключительные мысли

Так что помните, что вы смертный, а не непогрешимый мастер кодирования. И добавьте комментарии, которые сообщают о ваших намерениях. Затем выполните рефакторинг, используя лучшие имена, если сможете, удалите все комментарии, которые сможете, и добавьте комментарии о том, почему вам нужно было написать этот код в первую очередь.