Снабжайте файлы заголовками

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

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

/*********************************************************

*File: Foo.java

*Purpose: Foo class implementation

*Notice: (c) 1066 Foo industries. All rights reserved.

********************************************************/

Правильно обрабатывайте ошибки

Помещайте обработку всех ошибок в наиболее подходящий контекст. Если возникает проблема чтения/записи диска, ее нужно обрабаты% вать в том коде, который занимается доступом к диску. Для обработки этой ошибки может потребоваться сгенерировать другую ошибку (ти% па исключительной ситуации «не могу загрузить файл»), передав ее на более высокий уровень. Это означает, что на каждом уровне программы ошибка должна быть точным описанием проблемы в его контексте. Нет смысла обрабатывать ошибку, связанную со сбоем диска, в коде интерфейса пользователя.

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

Не выводите бессмысленных сообщений об ошибках. В зависимости от кон& текста представьте наиболее уместную информацию.

Пишите осмысленные комментарии

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