Листинг 31-61. Пример выделения комментария с помощью двух пустых строк (Java)

комментарий О

CodeStatementZero; CodeStatementOne;

комментарий 1

CodeStatementTwo; CodeStatementThree;

За исключением случаев, когда экранное пространство ограничено, это чисто эстетический вопрос, и вы можете решать его по своему усмотрению. В этой, как и во многих других ситуациях, сам факт наличия соглашения гораздо важней конкретных деталей этого соглашения.

31.7. Размещение методов

ЛвдекбШй»й есшка О доку- Методы состоят из отдельных операторов, данных, управ-ментйровший методов см тй- -ющих структур, комментариев - всех тех элементов, ко-раздвл «Комментирована «е- торые обсуждались в остальных частях этой главы. В дан-тодое» ртш D промассе ном разделе рассмотрены принципы форматирования, от-создашя метода см. раздел 9Л. носящиеся исключительно к методам. О разнице между хорошими и

ПЛОХИМИ методами см. главу 7. Используйте пустые строки для разделения составных частей метода Оставьте пустые строки между заголовком метода, объявлениями данных и именованных констант (если они есть) и телом метода.

Используйте стандартный отступ для аргументов метода Для форматирования заголовка метода можно задействовать те же, что и раньше, варианты форматирования: отсутствие определенного форматирования, форматирование в конце строки или стандартные размеры отступов. Как и в большинстве других случаев, стандартные отступы становятся наилучшим решением с точки зрения аккуратности, единообразия, удобства для чтения и исправления. Листинг 31-62 содержит два примера заголовков методов без определенного форматирования:

Листинг 31-62. Примеры заголовков методов,

не использующих определенного форматирования (С++)

bool ReadEmployeeData(int maxEmployees,EmployeeList *employees, EmployeeFile *inputFile,int *employeeCount,bool *isInputError)

void InsertionSort(SortArray data,int firstElement,int lastElement)

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

В качестве другого подхода к форматированию заголовка метода можно предложить форматирование в конце строки, обычно выглядящее неплохо. В листинге 31-63 приведены те же заголовки, отформатированные по-другому:

Листинг 31-63. Примеры заголовков методов

с посредственным форматированием в конце строки (С++)

bool ReadEmployeeData( int maxEmployees,

EmployeeList *employees,

EmployeeFile *inputFile,

int *employeeCount,

bool *isInputError )

0 приш-

нении параметров методов см. раздел 7.5.

void InsertionSort( SortArray data,

int firstElement,

int lastElement )

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

loyeeDataQ изменится на ReadNewEmployeeDataQ. Это нарушит выравнивание первой строки относительно остальных 4-х строк. Вам придется переформатировать 4 строки списка параметров, выравнивая их относительно новой позиции maxEmployees, вызванной более длинным именем функции. Вам может даже не хватить места с правой стороны экрана, поскольку элементы и так уже далеко сдвинуты вправо.

Примеры, приведенные в листинге 31-64, отформатированы с применением стандартных отступов. Они выглядят также эстетически привлекательно, но их сопровождение требует гораздо меньше усилий.

Листинг 31-64. Примеры заголовков методов, содержащих отступы стандартного размера (С++)

public bool ReadEmployeeData( int maxEmployees, EmployeeList *employees, EmployeeFile *inputFile, int employeeCount, bool *isInputError

public void InsertionSort( SortArray data, int firstElement, int lastElement

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

Этот стиль можно использовать в Visual Basic, хотя при этом потребуются символы продолжения строки (листинг 31-65):

Листинг 31-65. Пример заголовков методов, содержащих

стандартные отступы, удобные для чтения и сопровождения (Visual Basic)

- Символ « » используется как признак переноса строки.

l-Public Sub ReadEmployeeData (

ByVal maxEmployees As Integer,

ByRef employees As EmployeeList,

ByRef inputPile As EmployeeFile,

ByRef employeeCount As Integer,

ByRef isInputError As Boolean

31.8. Форматирование классов

в этом разделе рассказано об основных принципах размещения кода в классах. В первом подразделе вы узнаете, как отформатировать интерфейс класса, во втором - как оформлять реализацию класса, в последнем - мы обсудим организацию файлов и программ.

Форматирование интерфейсов классов

nipetpeemn ссылка О доку- Соглашение о размещении интерфейсов классов предусмат-итхщотт ттт см, «од- ривает перечисление членов класса в следующем порядке: раздел «Комментирование клас" 1. шапка с комментарием, содержащая описание класса и сов, файлов и программ» раа- любые примечания, касающиеся общих вопросов его ис-дела 32.5. О разнице «ежду пользования; хорошими и плохими классами

см. главу 6. 2. конструкторы и деструкторы;

3. открытые методы;

4. защищенные методы;

5. закрытые методы и члены-данные.

Форматирование реализаций классов

Реализации классов в общем случае могут размещаться в следующем порядке:

шапка с комментарием, описывающая содержимое файла с классом; данные класса; открытые методы; защищенные методы; закрытые методы.