Книга: Программирование на языке Пролог для искусственного интеллекта

8.3.3. Комментирование

8.3.3. Комментирование

Программные комментарии должны объяснять в первую очередь, для чего программа предназначена и как ею пользоваться, и только затем — подробности используемого метода решения и другие программные детали. Главная цель комментариев — обеспечить пользователю возможность применять программу, понимать ее и, может быть, модифицировать. Комментарии должны содержать в наиболее краткой форме всю необходимую для этого информацию. Недостаточное комментирование — распространенная ошибка, однако, программу можно и перенасытить комментариями. Объяснения деталей, которые и так ясны из самого текста программы, являются ненужной перегрузкой.

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

• Что программа делает, как ею пользоваться (например, какую цель следует активизировать и каков вид ожидаемых результатов), примеры ее применения.

• Какие предикаты относятся к верхнему уровню?

• Как представлены основные понятия (объекты)?

• Время выполнения и требования по объему памяти.

• Каковы ограничения на программу?

• Использует ли она какие-либо средства, связанные с конкретной операционной системой?

• Каков смысл предикатов программы? Каковы их аргументы? Какие аргументы являются "входными" и какие — "выходными", если это известно? (В момент запуска предиката входные аргументы имеют полностью определенные значения, не содержащие не конкретизированных переменных.)

• Алгоритмические и реализационные детали.

Оглавление книги