Внутренняя документация

В отличие от внешней внутренняя документация включается в сам код. Это наиболее подробный вид документации, относящийся к уровню команд исходного кода. Главный вклад в документацию уровня кода вносится не комментариями, а хорошим стилем программирования.

Комментарии Комментировать или не комментировать?

Комментарии легче написать плохо, а не хорошо, и комментирование иногда бывает скорее вредным, чем полезным. Наличие плохих комментариев хуже, чем их отсутствие. Иногда комментарии затрудняют чтение кода, а не облегчают. Естественный язык менее точен, чем Java или Visual Basic, и страдает от избыточности, тогда как операторы языков программирования лаконичны и попадают в самое яблочко. Если кто-то не может написать ясный код, разве ему удастся написать ясные комментарии? Кроме того, комментарии устаревают при изменениях кода. Злоупотребление комментариями возможно, но хорошие комментарии ценятся на вес золота. Хорошие комментарии не повторяют код и не объясняют его. Они поясняют его цель. Комментарии должны объяснять намерения программиста на более высоком уровне абстракции, чем код.

Виды комментариев

• Повторение кода. Такие комментарии не предоставляют дополнительной информации.

• Объяснение кода. Такие комментарии обычно служат для объяснения сложных, хитрых или нестабильных фрагментов кода. В этих ситуациях они полезны, но обычно только потому, что код непонятен. Если код настолько сложен, что требует объяснения, почти всегда разумнее улучшить код, а не добавлять комментарии

• Маркер в коде.

• Резюме кода. Эти комментарии более полезны, чем повторяющие, потому что программист, читающий программу, может просматривать их быстрее, чем код.

• Описание цели кода

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

К трем видам комментариев, приемлемых в готовом коде, относятся резюмирующие комментарии, комментарии цели и информация, не выразимая в форме кода.

Выводы

Хороший код сам является самой лучшей документацией. Если код настолько плох, что требует объемных комментариев, попытайтесь сначала улучшить его. Комментарии должны сообщать о коде что-то такое, что он не может сообщить сам — на уровне резюме или уровне цели. Некоторые стили комментирования заставляют выполнять много нудной канцелярской работы. Используйте стиль, который было бы легко поддерживать.

Обработка исключений

Исключения — это специальное средство, позволяющее передать в вызывающий код возникшие ошибки или исключительные ситуации. Если код в некотором методе встречает неожиданную ситуацию и не знает, как ее обработать, то он генерирует исключение, т. е. фактически умывает руки со словами: «Я не знаю, что с этим делать, надеюсь, кто-нибудь другой знает, как на это реагировать!» Код, не имеющий понятия о контексте ошибки, может вернуть управление другой части системы, которая, возможно, лучше знает, как интерпретировать ошибку и сделать с ней что-то осмысленное.

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

На заметку: PL/1 первый язык программирования, который стал поддерживать обработку исключений. В 1964 корпорация IBM создала PL/1, который заменил Cobol и Fortran в большинстве приложений. Также PL/1 первым стал поддерживать параллелизм.