Книга: Программирование на языке Пролог для искусственного интеллекта
8.3.3. Комментирование
8.3.3. Комментирование
Программные комментарии должны объяснять в первую очередь, для чего программа предназначена и как ею пользоваться, и только затем — подробности используемого метода решения и другие программные детали. Главная цель комментариев — обеспечить пользователю возможность применять программу, понимать ее и, может быть, модифицировать. Комментарии должны содержать в наиболее краткой форме всю необходимую для этого информацию. Недостаточное комментирование — распространенная ошибка, однако, программу можно и перенасытить комментариями. Объяснения деталей, которые и так ясны из самого текста программы, являются ненужной перегрузкой.
Длинные фрагменты комментариев следует располагать перед текстом, к которому они относятся, в то время как короткие комментарии должны быть вкраплены в сам текст. Информация, которую в самом общем случае следует включать в комментарии, должна схватывать следующие вопросы:
• Что программа делает, как ею пользоваться (например, какую цель следует активизировать и каков вид ожидаемых результатов), примеры ее применения.
• Какие предикаты относятся к верхнему уровню?
• Как представлены основные понятия (объекты)?
• Время выполнения и требования по объему памяти.
• Каковы ограничения на программу?
• Использует ли она какие-либо средства, связанные с конкретной операционной системой?
• Каков смысл предикатов программы? Каковы их аргументы? Какие аргументы являются "входными" и какие — "выходными", если это известно? (В момент запуска предиката входные аргументы имеют полностью определенные значения, не содержащие не конкретизированных переменных.)
• Алгоритмические и реализационные детали.
- 8.3. Стиль программирования
- 8.3.2. Табличная организация длинных процедур
- Общественное мнение и этические вопросы в прямом маркетинге
- 8.3 Writing HTML
- Концепция «Путь Samsung» как основа конкурентоспособности корпорации
- Когда использовать невидимый Интернет
- Вычислимость в классической физике: где мы находимся?
- Создание содержимого уровня блока: