Документирование задним числом
Одним из наиболее важных средств, способствующих пониманию программы, разработанной другими, является хорошая документация. Увы, очень и очень часто ее не оказывается и разбираться приходится, основываясь на документации, составленной задним числом. Разработать такую документацию гораздо труднее, чем документировать программу в процессе написания. Возможно, единственным достоинством такой документации является то, что она, если хорошо составлена, описывает те факты, которые действительно необходимо знать новому пользователю, чтобы разобраться в программе, а не те, которые, как предполагал автор, понадобятся новому пользователю.
Первое, что нужно сделать при разработке документации задним теслом, это получить распечатки программы. Желательно, чтобы они были расположены так, что оставалось бы достаточно места для пояснений. Если таких распечаток нет в Вашем распоряжении, то некоторые компиляторы могут выдать исходный текст с соответствующими отступами и разбиением на страницы. В противном случае можно воспользоваться специальными программами форматирования распечаток.
Отступы полезны, в частности, для прояснения условных и циклических конструкций. Если эти конструкции длинны, то без отступов может быть трудно определить их границы. Для выделения отдельных модулей каждый модуль должен печататься с новой страницы распечатки. Это и будет базовый текст программы. Если существует описание программы или модуля, то текст программы должен соответствовать этому описанию. Если описания нет, то разобраться в программе будет труднее и могут потребоваться вспомогательные средства.
Каковы бы ни были преимущества использования структурированного кода, блок-схемы все равно полезны для наглядного представления структуры сложных программ. Если их удастся начертить, то это будет еще одним средством, способствующим пониманию чужой программы. Несмотря на то, что блок-схемы могут быть составлены автоматически (для этого существует множество специальных программ), схема, начерченная вручную, может оказаться более полезной.
Блок-схемы, как и комментарии в хорошо написанной программе, должны указывать не только на то, что делает программа, но и почему она это делает, а это не всегда обеспечивается при автоматическом составлении блок-схемы, поскольку при этом используются лишь те комментарии и-операторы, которые имеются в исходном коде. Но так как вычерчивание блок-схем вручную требует времени, оно не практикуется или не требуется при составлении блок-схемы всей программы. Оптимальное решение может состоять в автоматическом составлении блок-схемы программы в целом с последующим уточнением сложных фрагментов вручную.