3.4 Комментарии и Выравнивание

3.4 Комментарии и Выравнивание

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

Неправильное использование комментариев может серьезно повлиять на удобочитаемость программы, Компилятор не понимает содержание комментария, поэтому он никаким способом не может убедиться в том, что комментарий

1. осмыслен,

2. описывает программу и

3. не устарел.

Непонятные, двусмысленные и просто неправильные комметарии содержатся в большинстве программ. Плохой комментарий может быть хуже, чем никакой.

Если что-то можно сформулировать средствами самого язка, следует это сделать, а не просто отметить в комментарии. Данное замечание относится к комментариям вроде:

// переменная "v" должна быть инициализирована.

//переменная"v"должна использоваться только функцией «f()».

// вызвать функцию init() перед вызовом // любой другой функции в этом файле.

// вызовите функцию очистки «cleanup()» в конце вашей // программы.

// не используйте функцию «wierd()».

// функция «f()» получает два параметра.

При правильном использовании С++ подобные комментарии как правило становятся ненужными. Чтобы предыдущие комментрии стали излишними, можно, например, использовать правила компоновки (#4.2) и видимость, инициализацию и правила очиски для классов (см. #5.5.2).

Если что-то было ясно сформулировано на языке, второй раз упоминать это в комментарии не следует. Например:

a = b+c; // a становится b+c count++; // увеличить счетчик

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

Автор предпочитает:

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

2. Комментарий для каждой нетривиальной функции, в ктором сформулировано ее назначение, используемый алгоритм (если он неочевиден) и, быть может, что-то о принимаемых в ней предположениях относительно среды выполнения,

3. Небольшое число комментариев в тех местах, где прорамма неочевидна и/или непереносима и

4. Очень мало что еще.

Например:

// tbl.c: Реализация таблицы имен /* Гауссовское исключение с частичным См. Ralston: «A first course ...» стр. 411. */

// swap() предполагает размещение стека AT amp;T sB20.

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

Copyright (c) 1984 AT amp;T, Inc. All rights reserved

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

Удачно подобранные и хорошо написанные комментарии – сщественная часть программы. Написание хороших комментариев может быть столь же сложным, сколь и написание самой програмы.

Заметьте также, что если в функции используются исключтельно комментарии //, то любую часть этой функции можно зкомментировать с помощью комментариев /* */, и наоборот.

Поделитесь на страничке

Следующая глава >

Похожие главы из других книг

8.2.3.6.4 Выравнивание

Из книги Информационная технология ПРОЦЕСС СОЗДАНИЯ ДОКУМЕНТАЦИИ ПОЛЬЗОВАТЕЛЯ ПРОГРАММНОГО СРЕДСТВА автора Автор неизвестен


Выравнивание и распределение

Из книги Photoshop. Мультимедийный курс автора Мединов Олег

Выравнивание и распределение Когда активен инструмент Перемещение, на панели под строкой меню появляется набор кнопок для выравнивания и распределения изображений и объектов (рис. 9.1). Рис. 9.1. Кнопки выравниванияПиктограммы на кнопках подсказывают, как будут


Выравнивание

Из книги Excel. Мультимедийный курс автора Мединов Олег

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


Выравнивание

Из книги Pinnacle Studio 11 автора Чиртик Александр Анатольевич

Выравнивание К нескольким выделенным, но не сгруппированным объектам можно также применять операцию автоматического выравнивания (имеется в виду пространственное положение объектов в кадре). Для его применения следует нажать кнопку на нижней панели инструментов или


Выравнивание и распределение

Из книги Adobe InDesign CS3 автора Завгородний Владимир

Выравнивание и распределение В тех случаях, когда необходимо расположить объекты с высокой точностью по отношению друг к другу (например, ровно в ряд на равном расстоянии), но точность расположения на странице не требуется, мы можем прибегнуть к процедурам выравнивания и


Выравнивание объектов

Из книги AutoCAD 2009 для студента. Самоучитель автора Соколова Татьяна Юрьевна

Выравнивание объектов Команда ALIGN осуществляет выравнивание объектов относительно других объектов в двумерном и трехмерном пространстве. Вызывается команда из падающего меню Modify ? 3D Operations ? Align.Запросы команды ALIGN: Select objects: – выбрать объекты Select objects: – нажать клавишу


Выравнивание объектов

Из книги 3ds Max 2008 для дизайна интерьеров автора Семак Рита

Выравнивание объектов В процессе работы часто приходится перемещать объекты, выравнивая их положение относительно друг друга. Например, при создании сложной модели, детали которой моделируются отдельно (допустим, люстры с подвесками в классическом стиле), на


Выравнивание

Из книги Word 2007.Популярный самоучитель автора Краинский И

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


Вертикальное выравнивание

Из книги XSLT автора Хольцнер Стивен

Вертикальное выравнивание Вертикальное выравнивание, в отличие от горизонтального (см. разд. 4.4), применяется не к строкам и абзацам, а к тексту целиком, поэтому относится к атрибутам, задающим компоновку страниц.Для установки параметров вертикального выравнивания


Автоматическое выравнивание

Из книги Разработка приложений в среде Linux. Второе издание автора Джонсон Майкл К.

Автоматическое выравнивание Элемент <xsl:output> поддерживает атрибут indent который устанавливается в «yes» или «no», и указывает процессору XSLT, нужно ли выравнивать результирующий документ. Как правило, выравнивание результирующего документа не имеет большого значения,


13.2.1. Выравнивание по страницам

Из книги Фундаментальные алгоритмы и структуры данных в Delphi автора Бакнелл Джулиан М.

13.2.1. Выравнивание по страницам Системная память делится на порции под названием страницы. Размер страницы изменяется в зависимости от архитектуры, и на некоторых процессорах размер страницы может изменяться ядром. Функция getpagesize() возвращает размер (в байтах) каждой


Выравнивание данных

Из книги AutoCAD 2009. Учебный курс автора Соколова Татьяна Юрьевна

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


Выравнивание объектов

Из книги AutoCAD 2008 для студента: популярный самоучитель автора Соколова Татьяна Юрьевна

Выравнивание объектов Команда ALIGN осуществляет выравнивание объектов относительно других объектов в двумерном и трехмерном пространстве. Вызывается команда из падающего меню Modify ? 3D Operations ? Align.Запросы команды


Выравнивание объектов

Из книги HTML, XHTML и CSS на 100% автора Квинт Игорь

Выравнивание объектов Команда ALIGN осуществляет выравнивание объектов относительно других объектов в двумерном и трехмерном пространстве. Вызывается команда из падающего меню Modify3D Operations ? Align.Запросы команды ALIGN:Select objects: – выбрать объектыSelect objects: – нажать клавишу Enter


Вертикальное выравнивание

Из книги Разработка ядра Linux автора Лав Роберт

Вертикальное выравнивание Свойство vertical-align каждой ячейки таблицы определяет вертикальное выравнивание ее содержимого. Содержимое каждой ячейки имеет базовую линию, верх, середину и низ. В контексте таблиц свойство vertical-align может принимать следующие значения.• baseline –


Выравнивание данных

Из книги автора

Выравнивание данных Выравнивание (alignment) соответствует размещению порции данных в памяти. Говорят, что переменная имеет естественное выравнивание (naturally aligned), если она находится в памяти по адресу, значение которого кратно размеру этой переменной. Например, переменная