Документирование программы

Программа, если она используется, живет не один год, и необходимость вносить в нее какие-то изменения и дополнения появляется сразу же после ввода в эксплуатацию. Сопровождение программы занимает гораздо больший промежуток времени, чем ее написание, поэтому документирование программы имеет очень большое значение. Основная часть документации должна находиться в тексте программы. Хорошие комментарии написать почти так же сложно, как и хорошую программу. Даже если сопровождающим программистом является автор программы, разбираться через год в плохо документированном тексте — сомнительное удовольствие.

В идеале комментарии должны создаваться до написания программы — ими служит подробный алгоритм, изложенный на естественном языке. Очень полезно до начала кодирования подробно записать, что и как должна делать программа (подпрограмма). Это помогает в деталях продумать алгоритм и интерфейсы, найти на самой ранней стадии серьезные ошибки и обеспечить содержательные комментарии. После такой работы программирование сводится к вставке фрагментов кода между комментариями. Подходить к написанию программы нужно таким образом, чтобы ее можно было в любой момент передать другому программисту.

Комментарии должны представлять собой правильные предложения без сокращений и со знаками препинания и не должны подтверждать очевидное.

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

Для разделения подпрограмм и других логически законченных фрагментов пользуйтесь пустыми строками или комментарием вида

{_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ }

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

Однако не следует пытаться оптимизировать все, что попадается под руку, поскольку главный принцип программиста тот же, что и врача: «Не навреди!» Если программа работает недостаточно эффективно, надо в первую очередь подумать о том, какие алгоритмы в нее заложены. Полезно также проанализировать программу с помощью профайлера, выявить узкие места и оптимизировать только их.