Глава 4. Компьютерная графика

/* модуль turtle*/

48

Ревизия: 170

Логические выражения, условия и рекурсия

Глава 5. Логические выражения, условия и рекурсия §5.1. Комментарии в программах

Любой дурак может написать программу, которую поймет компилятор. Хорошие программисты пишут программы, которые смогут понять другие программисты.

Мартин Фаулер (Martin Fowler), «Рефакторинг» ("Refactoring")

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

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

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

В Питоне комментарии помечаются символом # - строки, начинающиеся с этого символа, просто игнорируются интерпретатором и никак не влияют на ее трансляцию и выполнение:

# Подсчет процентного соотношения двух величин: 20 и 80

print 100 * 20 / 80, "%"

Комментарий может следовать и после инструкций, т.е. начинаться не с самого начала строки:

>» print 100 * 20 / 80, "%" # целочисленное деление

25 %

Кроме того, комментариями стоит снабжать и функции. Для этого предусмотрен еще один способ комментирования:

def printTwice(value):
"""Описание функции printTwice()
Данная функция получает значение и выводит	его дважды,	разделив
пробелом."""
print value, value

49

Ревизия: 170

Логические выражения, условия и рекурсия

Как видите, комментарии с описанием функций должны находиться сразу после заголовка функции. Они заключаются с двойные кавычки три раза и могут занимать несколько строк. Более того, в Питоне предусмотрена возможность вывода этих комментариев. Для этого достаточно воспользоваться встроенной переменной _doc_ (начинается и заканчивается парами символов подчеркивания):

>» print print-Twice. doc
Описание функции printTwice()
Данная функция получает значение и выводит	его дважды,	разделив
пробелом.

Этот же комментарий выведет команда справочной системы Питона help (printTwice).

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

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