Основы программирования

Наследство от языка Си - Комментарии и Выравнивание
Индекс материала
Наследство от языка Си
Область Видимости
Объекты и Адреса (Lvalue)
Имена
Типы
Неявное Преобразование Типа
Тип void
Указатели
Вектора
Структуры
Эквивалентность типов
Регистры
Константы
Символьные Константы
Строки
Const
Перечисления
Экономия Пространства
Упражнения
Выражения и Операторы
Программа синтаксического разбора
Функция ввода
Таблица имен
Обработка ошибок
Драйвер
Параметры командной строки
Краткая сводка операций
Порядок вычисления
Побитовые логические операции
Преобразование типа
Свободная память
Сводка операторов
Проверки
Goto
Комментарии и Выравнивание
Упражнения
Функции и Файлы
Компоновка
Заголовочные Файлы
Один Заголовочный Файл
Множественные Заголовочные Файлы
Сокрытие Данных
Файлы как Модули
Как Создать Библиотеку
Функции
ередача Параметров
Возврат Значения
Векторные Параметры
Параметры по Умолчанию
Перегрузка Имен Функций
Незаданное Число Параметров
Все страницы



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

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

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

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




 
Строительство бассейны сборный построить вентиляция бассейнов.