Приложение 5 Универсальный формат обмена данными
В данном Приложении описывается универсальный формат обмена данными, предназначенный для передачи данных во внешние системы и для получения данных от внешних систем. Данный формат также используется для передачи между компонентами ЦСОД, если способом передачи данных является файловый обмен.
Формат файла обмена данными представляет собой набор файлов, состоящих из:
Файла описания выгрузки данных в формате XML, схема которого представлена на рисунке.
Файла, содержащего данные в CSV-формате.
Файл описания выгрузки данных задает:
Описание выгружаемых данных в следующем составе:
Текстовое описание данных;
Информация о статистической работе, по которой получены данные;
Информация о файле данных и его формате (название файла, контрольная сумма, разделитель в файле и т.п.);
Дополнительные параметры, зависящие от обменивающихся систем.
Описание показателей, выгруженных в файл данных.
Рисунок – схема формата обмена данными
Приложение 6 Требования к организации и оформлению исходных текстов программ
Общие положения
Требования данного раздела должны применяться ко всем компонентам на языке программирования Java.
Термины и определения
Термин
|
Английское название
|
Выражение
|
Statement
|
Идентификатор
|
Identifier
|
Импортированный пакет
|
Import statement
|
Имя пакета
|
Package statement
|
Классы перечислений
|
Enum class
|
Объявление
|
Declaration
|
Пакет
|
Package
|
Переменная
|
Variable
|
Пробел
|
Horizontal whitespace
|
Разрыв строки
|
Vertical whitespace
|
Строка
|
Line
|
Правила хранения исходных кодов
Имя файла
Имя исходного файла должно состоять из регистрозависимого имени класса верхнего уровня, который содержится в данном файле, и расширения .java.
Имя файлов ресурсов должно быть с расширением, коррелирующем с содержанием файла.
Кодировка
Исходные файлы должны быть в кодировке UTF-8.
Специальные символы
Пробельные символы
Кроме символа окончания линии пробел должен быть единственным символом, который появляется в любом месте в исходном файле. Таким образом:
Все другие символы пробела в строке и символьных литералов экранированы.
Символы табуляции не используются для отступов.
Специальные последовательности
Любой символ (\b , \t , \n , \f , \r , \" , \' и \\ ), требующий экранирования, должен использовать последовательность экранирования вместо соответствующих восьмеричных (например, \012 ) или Unicode (например, \u000a) символов.
Остальные не-ASCII символы
Для остальных не-ASCII символов должны использоваться символы Unicode (например, ∞) или экранированные эквиваленты Unicode (например, \u221e), в зависимости от того, что будет легче читаться в коде.
Структура исходных файлов
Общие соглашения
Исходный файл должен состоять из следующих секций, по порядку:
Лицензии или информации об авторских правах, если они требуются.
Имени пакета.
Импортированных пакетов.
Строго одного класса верхнего уровня.
Все секции разделены строго одной строкой.
Имя пакета
Имя пакета не должно иметь перенос слов. Ограничение строки (см. подраздел 1.5.4) не применяется к имени пакета.
Импорт пакетов
Импорт по маске
Импорт по маске, статический или иной, запрещен.
Переносы в импорте
Перенос слов не должен использоваться для имен импортированных структур. Ограничение длины строки (см. подраздел 1.5.4) также не применяется.
Организация импорта
Импорт пакетов должен организовываться в следующие группы, разделенные одной строкой:
Все статические импортированные пакеты в одной группе.
Сторонние импортированные пакеты, отсортированные по алфавиту.
Импорты пакетов java.
Импорты пакетов javax.
Объявление класса
Объявление класса верхнего уровня
Должно быть строго одно объявление класса верхнего уровня. Каждый класс верхнего уровня находится в отдельном исходном файле.
Порядок членов класса
Каждый класс должен организовывать его члены в некоем логическом порядке, чтобы, при необходимости, разработчик мог пояснить организацию. Например, добавление новых методов в конец класса в хронологической последовательности не является логическим упорядочиванием.
Перегрузка
Если класс имеет несколько методов с одинаковым именем или несколько конструкторов, то они должны идти последовательно, без каких-либо промежуточных элементов.
Именование
Общие правила для всех идентификаторов
Идентификаторы должны использовать только ASCII-символы и цифры, кроме трех случаев, описанных ниже (см. п. 1.4.2.3, 1.4.2.4, 1.5.8.1). Таким образом, каждое валидное имя идентификатора будет соответствовать регулярному выражению «\w+».
Специальные префиксы или суффиксы такие, как name_, mName, s_name и kName, не должны использоваться.
Правила по типу идентификатора
Имена пакетов
Имена пакетов должны быть в нижнем регистре с последовательно соединенными словами без использования подчеркиваний.
Имена классов
Имена классов должны формироваться с использованием стиля UpperCamelCase.
Имена классов, как правило, являются существительными. Например, Character или ImmutableList. Имена интерфейсов, как правило, являются существительными. Например, List или прилагательными (например, Readable).
Тест-классы должны начинаться с имени тестируемого класса и заканчиваться постфиксом Test. Например, HashTest или HashIntegrationTest.
Имена методов
Имена методов должны формироваться с использованием стиля lowerCamelCase.
Имена методов, как правило, являются глаголами или глагольными словосочетаниями. Например, sendMessage или stop.
Разрешается использовать подчеркивания в именах методов тест-классов, чтобы логически разделить компоненты. Один из типичных шаблонов test _. Например testPop_emptyStack.
Константы
Имена констант должны использовать данный шаблон : все буквы заглавные, слова разделены подчеркиванием.
Каждая константа – это поле с модификаторами final static, но не все final static поля являются константами. Прежде чем обозначить константу, следует рассмотреть вопрос – действительно ли поле будет константой. Например, если какое-либо из наблюдаемого состояния этого экземпляра может измениться, то экземпляр, скорее всего, - не постоянная.
Имена константы, как правило, являются существительными.
Имена неконстантных полей
Имена неконстантных полей (статических или иных) должны формироваться с использованием стиля lowerCamelCase.
Эти имена, как правило, существительные. Например, computedValues или index.
Имена параметров
Имена параметров должны формироваться с использованием стиля lowerCamelCase.
Имена параметров, состоящие из одного символа, использовать запрещено.
Локальные имена переменных
Локальные имена переменных должны формироваться с использованием стиля lowerCamelCase. Разрешается сокращать их сильнее, чем другие типы имен.
Тем не менее, односимвольные имена использовать запрещено, за исключением временных переменных и переменных цикла.
Даже если локальные переменные помечены модификатором final и являются неизменяемыми, локальные переменные не будут являться константами и не должны быть именованы в стиле констант.
Имена generic типов переменных
Каждая переменная типа должна быть названа в одном из двух стилей:
одна заглавная буква, возможно сопровождаемая одной цифрой (например, E, T, X, T2);
имя, отвечающее правилам именования из п. 1.4.2.2, с добавленной буквой T (примеры: RequestT, FooBarT).
CamelCase
Для приведения к стилю CamelCase следует:
Преобразовать фразу в обычный ASCII и удалить все апострофы. Например, «Müller's algorithm» станет «Muellers algorithm».
Разделить результат из пункта 1 на слова, используя пробел или другие пунктуационные символы, как разделители.
Теперь перевести всё в нижний регистр (в том числе и сокращения), а потом перевести в верхний регистр только первый символ:
каждого слова, чтобы получить стиль UpperCamelCase;
каждого слова, за исключением первого, чтобы получить стиль lowerCamelСase.
Объединить все слова в один идентификатор.
Примечание - Некоторые слова в английском языке могут содержать или не содержать дефис, например, «nonempty» и «non-empty». Таким образом, название методов checkNonempty и checkNonEmpty будет корректно в обоих случаях.
Форматирование
Скобки
Использование скобок
Скобки должны использоваться всегда, даже если их можно не использовать.
Скобки должны использоваться всегда с конструкциями if, else, for, do и while, даже когда тело пустое или содержит только один оператор.
Непустые блоки: К & R стиль
Скобки должны подчиняться стилю Kernighan и Ritchie («Египетские скобки») для непустых блоков и блочных конструкций:
Нет разрыва строки до открывающей фигурной скобки.
Разрыв строки после открывающей фигурной скобки.
Разрыв строки до закрывающей скобки.
Разрыв строки после закрывающей скобки, если эта скобка завершает конструкцию блока или тело метода, конструктора или именованного класса. Например, нет разрыва строки после скобки, если она сопровождается конструкцией else или запятой.
Несколько исключений для перечислений приведены в п. 1.5.8.1.
Пустые блоки
Пустой блок разрешается закрыть сразу же после его открытия, без символов или разрыва строки «{}», если этот блок не является частью многоблочной конструкции (той, которая непосредственно содержит несколько блоков: if/else-if/else или try/catch/finally).
Отступ в блоках
Каждый раз, когда новый блок открывается, отступ должен увеличиваться на четыре пробела. Когда блок оканчивается, отступы должны возвращаться к предыдущему уровню. Уровень отступа относится и к коду, и комментариям внутри блока.
Одно выражение в линии
За каждым выражением должен следовать разрыв строки.
Размер строки
Максимальный размер строки должен быть не более 120 символов. За исключением случаев, указанных ниже, любая линия, которая превышает данный размер, должна быть разбита.
Исключения:
Строки, которые разбить невозможно (например, URL в Javadoc или метод JSNI).
Имя пакета и имена импортируемых пакетов.
Строки в комментариях, которые могут быть скопированы в командную строку.
Разрыв строки
Строки, которые превышают допустимый размер колонки, должны быть разбиты на строки.
Совет - Извлечение метода или локальной переменной может решить проблему без необходимости разрывать строку.
Места разрыва строки
При выборе места должно соблюдаться главное правило разрыва линии: предпочтительно делать разрывы на более высоком синтаксическом уровне, а именно:
Когда строка разбивается по оператору, отличному от оператора присваивания, разбитие происходит до символа оператора.
Когда строка разбивается по оператору присваивания, то разрыв обычно идет после символа, но обратное тоже допустимо.
Метод или конструктор остается связанным с открытой скобкой «(», что следует за ним.
Запятая «,» остается с выражением, которое предшествовало запятой.
Отступ при разрыве
Когда происходит разрыв строки, то следующая строка должна иметь отступ минимум 4 пробела от оригинальной строки.
Если происходит разрыв на несколько строк, то длина отступа может превышать 4 пробела.
Пробелы
Пустая строка
Пустая строка должна ставиться:
Между идущими подряд членами (или инициализаторами) класса: полями, конструкторами, методами, вложенными классами, статическими инициализаторами, инициализаторами экземпляра.
Исключение - Пустая строка между двумя последовательными полями (не имеющими никакого кода между ними) необязательна. Такие пустые строки используются, когда необходимо создать логическую группу полей.
В теле метода, когда надо создать логическую группу выражений.
Перед первым элементом или после последнего члена класса.
В соответствии с требованиями других разделов этого документа.
Разрешается использовать несколько пустых строк.
Пробелы
Кроме мест, требуемых языком, стилей оформления, комментариев и Javadoс, пробел должен появляться только в следующих местах:
Отделяя любое зарезервированное слово, например, if, for или catch, от открывающейся скобки «(», что следует за ним в этой строке.
Отделяя любое зарезервированное слово, например, else и catch, от закрывающейся фигурной скобки «}», который предшествует пробелу на этой строке.
Перед любой открытой фигурной скобкой «{», кроме двух исключений:
@({a, b}) (пробел не используется);
String[][] x = {{"foo"}}; (пробел не используется).
С обеих сторон любого бинарного или тернарного оператора. Это также относится к следующим символам:
амперсанд «&» в объединении типов: ;
знак «|» в блоке, который ловит несколько типов исключения: catch (FooException | BarException e);
знак двоеточие «:» в расширении оператора цикла for («foreach»).
После символов запятая «,», точка с запятой «;», двоеточие «:» или закрывающей скобки «)» после приведения типов.
С обеих сторон двойного слэша «//», с которого начинается комментарий в конце строки.
Между типом и объявлением переменной:
List list;
Внутри скобок инициализации массива:
new int[] {5, 6} и new int[] { 5, 6 } – Оба варианта верны
Группировка скобок
Группировка скобок в операторах должна присутствовать, если становится неочевидным приоритет выполнения операторов.
Конкретные конструкции
Классы перечисления
После каждой запятой, которая идет за константой перечисления, разрешен перенос строки.
Классы перечисления без методов разрешается оформить так, как если бы они были массивами с инициализацией.
private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }
Так как классы перечисления являются классами, то для них должны соблюдаться все правила форматирования классов.
В именах констант перечисления разрешается использовать кириллицу.
Имя класса должно отвечать правилам именования классов.
private enum DocumentStatus { СОГЛАСОВАН, НОВЫЙ, УТВЕРЖДЕН }
Объявление переменных
Одна переменная в объявлении
Каждое объявление переменных должно объявлять только одну переменную.
Переменные должны быть объявлены, когда требуются, и инициализированы так скоро, как это возможно.
Локальные переменные должны объявляться как можно ближе к месту их использования, чтобы снизить их зону видимости.
Локальные переменные разрешается инициализировать сразу или после объявления.
Массивы
Инициализация
Разрешено объявлять инициализацию массива как конструкцию блока. С-стиль объявления массива
Запрещено использовать стиль языка С для объявления массива.
Оператор Switch
Отступы
Как и в любой другой конструкции содержимое блока Switch должно иметь отступ в четыре пробела.
После появления case-значения уровень отступа повышается на 4 пробела, как будто был открыт новый блок. Следующее case-значение должно возвращаться к предыдущему уровню отступа, как будто блок был закрыт.
Выполнение блоков
Каждый блок должен завершаться принудительно оператором break, continue, return или выбрасывать исключение, или должен быть помечен обязательным комментарием, что выполнение должно продолжиться в следующем блоке.
Условие по умолчанию
Каждый оператор Switch должен иметь блок default, даже если он будет пустой. В случае пустого блока следует оставить комментарий с пояснением, что данный случай был специально проигнорирован, или вызвать исключение с указанием причины.
Аннотации
Аннотации, применяемые к классу, методу или конструктору, должны следовать сразу за блоком с комментарием Javadoc и каждая аннотация должна занимать свою строчку. Аннотации не подчиняются правилам разрыва строки и уровень отступа не увеличивается.
Исключение: разрешается располагать одну аннотацию без параметров на той же строке, что и сигнатура метода.
@Override public int hashCode() { ... }
Аннотации, применяемые к полю, должны следовать сразу за блоком с документацией, но если их несколько, то разрешается их разместить на одной линии.
Комментарии
Блочные комментарии
Блочные комментарии должны быть на том же уровне отступов, что и окружающий код. Для одиночных комментариев применяется стиль «/* */» или «//…». Для многострочного комментария применяется стиль «/* …. */», где следующая линия в комментарии стартует с символа звездочка «*».
/ *
* Это // И так / * Или даже разрешено
* разрешено. // разрешено. * сделать так. * /
* /
Модификаторы
Модификаторы классов и членов должны располагаться в порядке, рекомендованном Java Language Specification:
public protected private abstract static final transient volatile synchronized native strictfp
Числовые символы
Целые числа типа long должны использовать суффикс L.
Общие практики
Аннотация override
Метод должен быть аннотирован аннотацией @Override, если он перегружает метод родительского класса или если он реализует метод интерфейса.
Исключение - @Override может быть опущен, если родительский метод помечен аннотацией @Deprecated.
Проверяемые исключения
Проверяемые (checked) исключения не должны игнорироваться.
За исключением случаев, указанных ниже, проверяемые исключения должны быть залогированы или, если считается, что они невозможны, то необходимо оставить выброс AssertionError.
Когда исключение действительно может быть проигнорировано, то должен быть оставлен комментарий с пояснением.
Исключение - В тестах проверяемые исключения разрешено игнорировать без комментария, если исключение называется expected.
Статические члены
Статические члены должны вызываться у класса, а не у экземпляра.
Финализаторы
Использование метода finalize запрещено, кроме двух исключений:
Разрешается использовать финализатор, если необходимо оставить последнюю возможность освободить ресурс и запротоколировать то, что разработчик забыл освободить ресурс.
При работе из java c нативным кодом, чтобы вызвать цепочку освобождения ресурсов.
При необходимости закрывать ресурс следует пользоваться интерфейсами Closable или AutoClosable, либо предоставлять отдельный метод, который будет вызван в finally блоке.
Javadoc
Форматирование
Общий вид
Основное форматирование Javadoc-комментария должно соответствовать примеру:
/**
* Javadoc
* Доп. строка
*/
public int method(String p1){...}
Разрешается использовать однострочный комментарий:
/ ** Строка Javadoc. * /
Параграфы
Между параграфами должна быть одна пустая строка, начинающаяся с *. Каждый параграф, кроме первого, должен иметь тэг
перед первым словом без пробелов.
Дескрипторы
Любой из этих четырех дескрипторов @param, @return, @throws, @deprecated должен сопровождаться описанием.
Описание
Javadoc-комментарий для класса или члена класса должен начинаться с краткого описания.
Использование Javadoc
Javadoc-комментарий должен быть описан для каждого публичного класса и для каждого публичного, защищенного или видимого внутри пакета метода данного класса, кроме ситуаций, описанных ниже.
Если комментарий описывает цель или поведение класса, метода или поля, то он должен быть Javadoc-комментарием.
Общие принципы ведения Javadoc
Комментарии должны вестись на русском языке. Автоматически генерируемые применяемым в проекте инструментарием комментарии могут быть на английском.
Использование Javadoc-комментариев при написании кода является обязательным. Данными комментариями должны быть описаны следующие элементы кода:
Классы.
Публичные методы классов.
Публичные атрибуты классов, константы.
Javadoc-комментарий к классу должен включать в себя следующие элементы:
Описание класса.
Также могут быть указаны дополнительные ссылки на другие классы с использованием тегов @see, @link.
Javadoc-комментарий к методу класса должен включать в себя следующие элементы:
Описание метода.
Список параметров метода (с использованием тега @param) с описанием.
Описание возвращаемого методом значения (с использованием тега @return).
Перечень возможных исключений (с использованием тега @throws).
Указание на то, что метод устарел и не рекомендуется к применению (с использованием тега @deprecated), в описании должно быть указано, какой метод рекомендуется использовать взамен устаревшего.
Javadoc-комментарий к атрибуту класса (константе) должен включать в себя описание атрибута.
Исключения
Javadoc разрешается пропускать для методов, чье название говорит само за себя. Например, getFoo.
Javadoc разрешается пропускать для метода, который переопределяет метод супертипа.
|
