51 Основные правила оформления программной документации.
При оформлении текстовых и графических материалов, входящих в программную документацию следует придерживаться действующих стандартов. Некоторые положения этих стандартов приведены ниже.
Оформление текстового и графического материала. Текстовые документы оформляют на листах формата А4, причем графический материал допускается представлять на листах формата A3. Поля на листе определяют в соответствии с общими требованиями: левое - не менее 30, правое - не менее 10, верхнее - не менее 15, а нижнее - не менее 20 мм. В текстовых редакторах для оформления записки параметры страницы заказывают в зависимости от устройства печати. При ручном оформлении документов параметры страницы выбирают из соображений удобства.
Нумерация всех страниц - сквозная. Номер проставляется сверху справа арабской цифрой. Страницами считают, как листы с текстами и рисунками, так и листы приложений. Первой страницей считается титульный лист. Номер страницы на титульном листе не проставляют.
Наименование разделов пишут прописными буквами в середине строки. Расстояние между заголовками и текстом, а также между заголовками раздела и подразделов должно быть равно:
-при выполнении документа машинописным способом - двум интервалам;
-при выполнении рукописным способом - 10 мм;
-при использовании текстовых редакторов - определяется возможностями редактора.
Наименования подразделов и пунктов следует размещать с абзацного отступа и печатать вразрядку с прописной буквы, не подчеркивая и без точки в конце. Расстояние между последней строкой текста предыдущего раздела и последующим заголовком при расположении их на одной странице должно быть равно:
-при выполнении документа машинописным способом - трем интервалам;
-при выполнении рукописным способом - не менее 15 мм;
-при использовании текстовых редакторов - определяется возможностями редактора.
Разделы и подразделы нумеруются арабскими цифрами с точкой. Разделы должны иметь порядковые номера 1, 2, и т. д. Номер подраздела включает номер раздела и порядковый номер подраздела, входящий в данный раздел, разделенные точкой. Например: 2.1, 3.5. Ссылки на пункты, разделы и подразделы указывают, используя порядковый номер раздела или пункта, например, «в разд. 4», «в п. 3.3.4».
Текст разделов печатают через 1,5 - 2 интервала. При использовании текстовых редакторов высота букв и цифр должна быть не менее 1,8 мм (шрифты № 11-12).
Перечисления следует нумеровать арабскими цифрами со скобкой, например: 2), 3) и т.д. - с абзацного отступа. Допускается выделять перечисление постановкой дефиса перед пунктом текста или символом, его заменяющим, в текстовых редакторах. Оформление рисунков, схем алгоритмов, таблиц и формул. В соответствии с ГОСТ 2.105-79 «Общие требования к текстовым документам» иллюстрации (графики, схемы, диаграммы) могут быть приведены как в основном тексте так и в приложении. Все иллюстрации именуют рисунками. Все рисунки, таблицы и формулы нумеруют арабскими цифрами последовательно (сквозная нумерация) или в пределах раздела (относительная нумерация). В приложении - в пределах приложения.
Каждый рисунок должен иметь подрисуночную подпись - название, помещаемую под рисунком, например:
Рис.12. Форма окна основного меню
На все рисунки, таблицы и формулы в записке должны быть ссылки в виде: «(рис. 12)» или «форма окна основного меню приведена на рис. 12».
Если позволяет место, рисунки и таблицы должны размещаться сразу после абзаца, в котором они упоминаются в первый раз, или как можно ближе к этому абзацу на следующих страницах.
Если рисунок занимает более одной страницы, на всех страницах, кроме первой, проставляется номер рисунка и слово «Продолжение». Например:
Рис. 12. Продолжение
Рисунки следует размещать так, чтобы их можно было рассматривать без поворота страницы. Если такое размещение невозможно, рисунки следует располагать так, чтобы для просмотра надо было повернуть страницу по часовой стрелке. В этом случае верхним краем является левый край страницы. Расположение и размеры полей сохраняются.
Схемы алгоритмов должны быть выполнены в соответствии со стандартом ЕСПД. Толщина сплошной линии при вычерчивании схем алгоритмов должна составлять от 0.6 до 1.5 мм. Надписи на схемах должны быть выполнена чертежным шрифтом, высота букв и цифр должна быть не менее 3,5 мм.
Номер таблицы размещают в правом верхнем углу или перед заголовком таблицы, если он есть. Заголовок, кроме первой буквы, выполняют строчными буквами. Ссылки на таблицы в тексте пояснительной записки указывают в виде слова «табл.» и номера таблицы, например:
Результаты текстов приведены в табл. 4.
Номер формулы ставится с правой стороны страницы в круглых скобках на уровне формулы, например:
z=sin(x)+ln(y) (12)
Ссылка на номер формулы дается в скобках. Например: «расчет значений проводится по формуле (12)».
Оформление приложений. Каждое приложение должно начинаться с новой страницы с указание в правом углу слова «ПРИЛОЖЕНИЕ» прописными буквами и иметь тематический заголовок. При наличии более одного приложения все они нумеруются арабскими цифрами: ПРИЛОЖЕНИЕ 1, ПРИЛОЖЕНИЕ 2 и т.д. Например:
ПРИЛОЖЕНИЕ 2
Рисунки и таблицы, помещаемые в приложении, нумеруют арабскими цифрами в пределах каждого приложения с добавлением буквы «П». Например:
Рис. П. 12 - 12-й рисунок приложения;
Рис. П1.2 - 2-й рисунок 1-го приложения.
Если в приложении приводится текст программы, то каждый файл оформляют как рисунок с наименованием файла и его назначением, например:
Рис. П2.4. Файл menuran.cpp - программа обработки основного меню.
Оформление списка литературы. Список литературы должен включать все использованные источники. Сведения о книгах (монографиях, учебниках, пособиях, справочниках и т. д.) должны содержать: фамилию и инициалы автора, заглавие книги, место издания, издательство, год издания. При наличии трех и более авторов допускается указывать фамилию и инициалы только первого из них со словами «и др.». Издательство надо приводить полностью в именительном падеже: допускается сокращение названия только двух городов: Москва (М.) и Санкт-Петербург (СПб.).
Сведения о статье из периодического издания должны включать: фамилию и инициалы автора, наименования статьи, издания (журнала), серии (если она есть), номер издания (журнала) и номера страниц, на которых помещена статья.
При ссылке на источник из списка литературы (особенно при обзоре аналогов) надо учитывать порядковый номер по списку литературы, заключенный в квадратные скобки; например: [5].
Обзор новых ключевых слов и типов данных
Согласно Рекомендациям комитета ANSI, работаюшего над Standart C++, в Visial C++ добавлен ряд новых ключевых слов. К ним относятся: bool, true, false, mutable, typename и explicit.
Тип данных bool
Новый тип данных bool является специальным целочисленным типом, который может принимать только значения true и false. Это формальная замена неформальных конструкций #define и typedef, которыми программисты на C++ пользовались многие годы. Большинство условных выражений, таких как (i != 0) или (а<b) теперь возвращают значение bool, а не int.
Ключевое слово mutable
Ключевое слово mutable используется для того, чтобы считать данный объект исключением из правил обработки С-объектов с модификатором const. К примеру, предположим, что у нас имеется класс Account, в котором необходимо выполнять одни и те же значительные по объему вычисления в начале каждой из его функций-членов. Вы решили хранить результат этих вычислений в закрытой переменной-члене данного объекта. Подобный класс может выглядеть следующим образом:
class Account
{
private:
// различные данные
float value;
bool valueok;
public:
const void PrintStatement(CTime starttime);
float GetValue() ;
void CreditSalesRep(SalesRep& owner);
void Deposit (float amt) ;
// и так далее
private
void UpdateValue();
};
void Account::PrintStatement(CTirae starttirae)
{
if (!valueok)
{
UpdateValue();
valueok = true;
}
// концовка функции
}
void Account: : Deposit (float amt)
{
valueok = false;
// окончание функции
}
// остальные функции
Как правило, определение класса приобретает подобный вид не сразу. Вероятно, прежде все функции при каждом обращении просто вызывали UpdateValue(), пока кто-то не обратил внимание на низкую производительность программы и не решил хранить значение Value непосредственно в объекте, чтобы не требовалось вызывать функцию UpdateValue() столь часто. Эти изменения затронули только раздел private-объекта и не имели никакого влияния на остальной текст программы, использующий этот объект.
Однако тут есть маленькое но: что если одна из функций-членов была объявлена с квалификатором const? Функция PrintStatement , например, действительно не изменяет объект Account или, она не делала это до тех пор, пока не была добавлена переменная valueok. Но теперь, если вы попробуете объявить функцию PrintStatement(), как имеющую квалификатор const, компилятор выдаст сообщение об ошибке, поскольку она меняет значение переменной valueok.
Если оператор valueok=true перенести в конец функции UpdateValue() и объявить эту функцию-член с квалификатором const, то тогда функция Printstatement() скомпилируется успешно, но при компиляции функции UpdateValue() на строке valueok=true будет сформировано сообщение об ошибке.
Раньше программисты обходили подобные ситуации, вообще отказываясь от использования квалификатора const, что было опасно и ухудшало читабельность программы. Теперь же нужно просто объявить переменные value и valueok с квалификатором mutable:
private:
// различные переменные
mutable float value;
mutable bool valueok;
Это объявление указывает на то, что правила работы с квалификатором const не распространяются на эти переменные-члены, и они могут быть изменены даже функциями, объявленными с квалификатором const. Это даст вам возможность сохранить "концептуальную константность" функций и повысить читабельность создаваемых программ.
Ключевое слово typename
Это ключевое слово применяется только в шаблонах и означает, что используемое вами в данном случае имя является именем типа, а не именем переменной. Оно также может заменять слово class в определении шаблона.
Ключевое слово explicit
Это ключевое слово уже встречалась нам выше в определении шаблона класса auto_ptr. Оно может использоваться только в конструкторах и присутствует только в их объявлении, как показано ниже:
class Foo
{
explicit Foo() {data=0;} // допустимо
explicit Foo(int i); // допустимо
// остальная часть класса
};
explicit Foo::Foo(int i) //так нельзя
{
data=i;
}
Foo: :Foo(int i) // допустимо, т.к. в описании класса для этого конструктора указан квалификатор explicit
{
data=i;
}
Что же означает описание конструктора с квалификатором? Это означает, что для него не должны применяться некоторые скрытые преобразования, которые обычно выполняются компиляторами.
Рассмотрим следующий фрагмент текста
void func(Foo f);
//
func(3);
//…
Во время компиляции этого фрагмента компилятор попробует преобразовать тип int в тип Foo. Вероятнее всего, он сформирует программный текст, похожий на следующий:
{
Foo compiler_temporary (3);
func(compiler_temporary);
}
Если вы добавите в конструктор и деструктор операторы трассировки, то сможете увидеть, насколько часто компилятору приходится выполнять неявные преобразования подобного типа.
Ключевое слово explicit указывает компилятору на то, что в конструкторе нельзя проводить подобных неявных преобразований. Так как конструктор Foo(), принимающий значение типа int, объявлен как explicit, компилятор не сможет проводить такие преобразования и вызов функции func не будет компилироваться.
Спрашивается, зачем нужно писать такой программный текст, который невозможно компилировать? Дело в том, что если бы он скомпилировался, то было бы еще хуже. Если бы Foo был управляемым указателем, то когда переменная compiler_temporary вышла бы из области видимости, память, на шор она указывала, была бы удалена, а в программе возникла бы серьезная ошибка Если же вы хотите использовать функцию func, то самостоятельно создайте объект типа Foo и передайте его в качестве аргумента. Только в таком случае вы избежите ошибки.