Требования к исходному коду программ на языке JAVA
Редакция 1.0 от ____.____.2008 г.
Страниц (включая титульную):
Согласовано
____________________________
|
________________
|
«_____»_________ 2008 г.
|
____________________________
|
________________
|
«_____»_________ 2008 г.
|
____________________________
|
________________
|
«_____»_________ 2008 г.
|
____________________________
|
________________
|
«_____»_________ 2008 г.
|
____________________________
|
________________
|
«_____»_________ 2008 г.
|
____________________________
|
________________
|
«_____»_________ 2008 г.
|
____________________________
|
________________
|
«_____»_________ 2008 г.
|
____________________________
|
________________
|
«_____»_________ 2008 г.
|
____________________________
|
________________
|
«_____»_________ 2008 г.
|
Утверждаю
____________________________
|
.
|
«_____»_________ 2008 г.
|
Содержание
Введение 4
Назначение документа 4
Рамки документа 4
Ссылки 4
Термины и определения 4
Размещение исходного кода 4
Форматирование исходных Java-файлов 5
Организация файла 5
Начальный комментарий 5
package и import инструкции 5
Определения классов и интерфейсов 6
Полный пример 6
Отступы 7
Длина строк и переносы 7
Пустые строки 7
Комментарии в исходных Java-файлах 7
Документирование исходного кода 8
Именование 8
Общие правила именования 8
Именование файлов 8
Именование пакетов 8
Именование классов и интерфейсов 8
Именование методов 8
Именование переменных 9
Именование констант 9
Декларации 9
Число деклараций на строку 9
Инициализация переменных 9
Расположение деклараций 9
Декларации классов и интерфейсов 10
Массивы 10
Инструкции 10
Простые инструкции 10
Составные инструкции 10
Инструкции if, if-else, if else-if else 11
Инструкция for 11
Инструкция while 11
Инструкция do-while 11
Инструкция switch 11
Инструкция try-catch 12
Обработка ошибок 12
Доступ к методам и переменным 12
Доступ к атрибутам класса 12
Доступ к статическим методам и переменным 12
Константы 12
Присваивание переменным 12
Оформление Java Server Pages (JSP) 13
Выполнение требований стандарта 13
Контроль соответствия разрабатываемого кода настоящему стандарту 13
Приложение А. Пример Java-кода 14
Введение
Назначение документа
Данный документ является корпоративным стандартом предприятия, определяющим требования к разработке исходного Java-кода. Документ входит в группу стандартов предприятия, определяющих требования к разработке исходного кода на языках программирования.
Задачи стандарта:
упростить поддержку программного обеспечения за счет унификации;
обеспечить возможность поддержки и развития программного продукта не его первоначальными авторами за счет улучшения читаемости исходного кода;
обеспечить возможность работы с исходным кодом (при его продаже в составе программного продукта) специалистам покупателя.
Рамки документа
В документе определены требования к разработке исходного Java-кода, в т.ч. требования к оформлению кода Java Server Pages (JSP).
В стандарте не определяются принципы проектирования исходного кода, конкретные средства разработки, а также способы компиляции, сборки проектов и другие технологические операции, осуществляемые в процессе разработки программного обеспечения.
Ссылки
При подготовке документа использованы рекомендации Sun Microsystems, Inc. по оформлению Java-кода, опубликованные по адресу http://java.sun.com/docs/codeconv/
Термины и определения
Исходные Java-файлы – файлы, содержащие определения Java-классов на языке Java.
JSP-файлы – файлы, содержащие код в формате JSP.
Исходный Java-код – исходные Java-файлы и JSP-файлы.
Размещение исходного кода
Весь разрабатываемый исходный код проекта помещается в единый репозитарий, поддерживающий контроль версий, многопользовательскую работу, аутентификацию, авторизацию, журналирование операций и возможность доступа через Internet. Например, SVN, CVS, Rational ClearCase, Microsoft Visual SourceSafe и т.п.
Выбор конкретного средства для хранения исходного кода определяется руководителем проекта в соответствии с особенностями проекта.
Форматирование исходных Java-файлов
Организация файла
Составные части исходного кода разделяются пустыми строками и дополнительными комментариями.
Файлы размером свыше 2000 строк желательно разделять на несколько отдельных файлов.
Каждый исходный Java-файл может содержать только один public класс или интерфейс. Public класс или интерфейс должен быть определён первым в исходном java-файле.
Исходный Java-файл должен состоять из следующих составных частей (далее секций):
Начальный комментарий;
package и import инструкции;
Определения классов и интерфейсов.
Начальный комментарий
Все файлы исходного кода системы должны начинаться с комментария, содержащего информацию об авторских правах:
/*
* Copyright 2005-2006 ЗАО «Диасофт». All rights reserved.
*/
package и import инструкции
Следующим за описанием файла, без пробела, следует объявление пакета, затем через пробел должны идти объявления импортируемых классов или интерфейсов. Пример:
package ru.diasoft.richclient.ui.dynamic.impl;
import java.awt.Component;
import java.awt.Frame;
import java.awt.Window;
Порядок импорта должен быть разбит на следующие группы:
java
javax
org
net
com
ru
Между каждой группой импорта должен быть один пробел, внутри группы, импортируемые классы должны быть упорядочены по алфавиту. Не допускается использование символа * в инструкциях импорта (каждый импортируемый класс или интерфейс записывается отдельной строкой).
Пример:
package ru.diasoft.richclient.ui.dynamic.impl;
import java.awt.Component;
import java.util.Date;
import java.util.ResourceBundle;
import javax.swing.DefaultListModel;
import javax.swing.JList;
import org.apache.commons.lang.StringUtils;
import org.mozilla.javascript.Context;
import org.mozilla.javascript.Function;
import ru.diasoft.fa.platform.ui.swing.widget.WCheckBox;
import ru.diasoft.fa.platform.ui.swing.widget.WComboBox;
Определения классов и интерфейсов
Часть содержит определения классов и интерфейсов на языке Java и комментарии к ним.
Перед названием класса или интерфейса должен присутствовать комментарий содержащий информацию о авторе и номер версии файла, далее без пробела определение класса или интерфейса.
Пример:
/**
* @author Andrey Ivanov
* @version $Revision: 1.19 $
*/
public class Blah extends SomeClass {
/* A class implementation comment can go here. */
/** classVar1 documentation comment */
public static int classVar1;
public Blah() {
// …implementation goes here..
}
Полный пример
/*
* Copyright 2005-2006 ЗАО «Диасофт». All rights reserved.
*/
package ru.diasoft.richclient.ui.dynamic.impl;
import java.awt.Component;
import java.util.Date;
import java.util.ResourceBundle;
import javax.swing.DefaultListModel;
import javax.swing.JList;
import org.apache.commons.lang.StringUtils;
import org.mozilla.javascript.Context;
import org.mozilla.javascript.Function;
import ru.diasoft.fa.platform.ui.swing.widget.WCheckBox;
import ru.diasoft.fa.platform.ui.swing.widget.WComboBox;
/**
* @author Andrey Ivanov
* @version $Revision: 1.19 $
*/
public class Blah extends SomeClass {
/* A class implementation comment can go here. */
/** classVar1 documentation comment */
public static int classVar1;
public Blah() {
// …implementation goes here..
}
Отступы
В качестве единицы пространства для отступов слева от кода следует использовать 4 пробела.
Длина строк и переносы
Длина строк исходного Java-файла не должна превышать 120 символов
Если выражение не может уместиться в одну строку, то его следует разбить на несколько строк в соответствии со следующими принципами:
Строка может быть прервана после запятой;
Строка может быть прервана перед оператором;
При переносе выражения, вторая строка должна иметь отступ 8 пробелов по отношению к первой, все следующие строки должны быть выровнены по тому же уровню, что и вторая строка выражения.
Например:
//CONVENTIONAL INDENTATION
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
…
}
//INDENT 8 SPACES TO AVOID VERY DEEP INDENTS
private static synchronized horkingLongMethodName(int anArg,
Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
…
}
Пустые строки
Пустые строки следует использовать для деления файла на логические части.
Две подряд пустые строки следует использовать в следующих случаях:
Между секциями исходного файла;
Между определениями классов и интерфейсов.
Одна пустая строка должна использоваться в следующих случаях:
Между методами;
Перед блочными и однострочными комментариями;
Между логическими частями внутри метода для увеличения его читаемости.
Комментарии в исходных Java-файлах
Исходный Java-файл может содержать комментарии двух типов
Комментарии, подобные C++, и определяемые символами /*…*/ или //
Комментарии для утилиты javadoc, определяемые как /**…*/
Комментарии, подобные C++, следует использовать в случае, если их предполагается читать только при непосредственном просмотре исходного кода.
Комментарии javadoc используются для автоматического построения документации по исходному коду. Они используются как при непосредственном просмотре документа, так и в качестве описаний классов, интерфейсов, методов и атрибутов в документации, автоматически создаваемой утилитой javadoc.
Каждый public или protected класс, интерфейс, метод и атрибут должны содержать комментарий для построения документации утилитой javadoc.
Необходимость включения дополнительных комментариев определяется разработчиком или руководителем проекта.
Комментарии должны упрощать понимание исходного программного кода.
Документирование исходного кода
По исходному java-коду при помощи утилиты javadoc должна автоматически формироваться документация в HTML-формате.
Исходный код должен содержать достаточно комментариев для описания в создаваемой утилитой javadoc документации каждого public и protected класса, интерфейса, метода и атрибута.
Именование
Общие правила именования
Именование должно упрощать понимание программного кода и облегчать его чтение.
Имена пакетов, классов, методов и атрибутов и констант должны соответствовать реализуемой ими функциональности.
Именование файлов
Исходные Java-файлы должны иметь имя, совпадающее с именем содержащегося в них public класса или интерфейса и иметь расширение .java, в соответствии с правилами языка Java.
JSP-файлы должны иметь расширение .jsp и имя состоящее только из латинских букв, цифр и символов подчёркивания без пробелов. Имя JSP-файла должно соответствовать выполняемым им операциям.
Именование пакетов
Имена пакетов должны начинаться с ru.diasoft. и далее содержать уникальное имя, состоящее только из латинских букв нижнего регистра (ASCII 97-122) и точек в качестве разделителя подпакетов.
Пример:
package ru.diasoft.rual.eip.users;
Именование классов и интерфейсов
Классы именуются буквами смешанного регистра. С буквы верхнего регистра начинается каждое слово, составляющее имя класса, остальные буквы слова пишутся в нижнем регистре. Для именования классов следует использовать правильные слова английского языка. Не допускается использование сокращений, кроме общепринятых. В аббревиатурах верхний регистр следует использовать только для первой буквы аббревиатуры, остальные буквы аббревиатуры пишутся в нижнем регистре.
Пример:
public class HttpUserRepository {
...
Именование методов
Методы должны именоваться по тому же принципу, что и классы, но все имена методов и атрибутов должны начинаться с буквы нижнего регистра
Пример:
public void doSomething() {
// ...implementation goes here...
}
Именование переменных
Атрибуты и переменные именуются по тому принципу, что и методы, за исключением временных переменных, которые допускается именовать одной буквой.
Не допускается начинать имена переменных с символов “_” и “$”.
Именование констант
Имена констант должны состоять из букв верхнего регистра и символа _ в качестве разделителя строк. В именах констант не должны использоваться не общепринятые сокращения.
Пример:
static final int MAX_WIDTH = 999;
Декларации
Число деклараций на строку
Не допускается в одну строку включать несколько деклараций.
Пример правильных деклараций:
String managerName;
int code;
Пример неправильных деклараций:
String managerName; int code; // НЕДОПУСТИМО!
Инициализация переменных
Следует инициализировать переменные при объявлении в случаях, если начальное значение переменной не зависит от вычислений.
Расположение деклараций
Декларации должны располагаться в начале программных блоков.
Пример:
void myMethod() {
int int1 = 0; // beginning of method block
if (condition) {
int int2 = 0; // beginning of "if" block
...
}
}
Не допускается во вложенных блоках использовать имена переменных, совпадающие с именами внешних блоков
Пример:
int count;
...
myMethod() {
if (condition) {
int count = 0; // НЕДОПУСТИМО!
...
}
...
}
Декларации классов и интерфейсов
В декларациях классов и интерфейсов следует соблюдать следующие принципы:
Символ «{» должен находиться в конце первой строки декларации;
Символ «}» должен быть единственным символом последней строки декларации, за исключением пустых деклараций, которые могут быть записаны целиком в одну строку;
Между именем методов и символом «(», начинающим список параметров, не должно быть пробелов.
Массивы
При инициализации массива, отсутствуют пробелы после начальной фигурной скобки и перед конечной фигурной скобкой.
Пример:
int[] array1 = new int[] {1, 2, 3};
int[] array2 = new int[] { 1, 2, 3 }; // НЕДОПУСТИМО!
Инструкции
Простые инструкции
Каждая строка должна содержать не более одной инструкции.
Пример правильного оформления инструкций:
argv++; // Correct
argc--; // Correct
Пример неправильного оформления инструкций:
argv++; argc--; // НЕДОПУСТИМО!
Составные инструкции
Составные инструкции - это инструкции, состоящие из набора инструкций, заключённого между символами «{» и «}».
При оформлении составных инструкций следует соблюдать следующие принципы
Вложенные инструкции должны оформляться с отступом по отношению к внешней инструкции;
Символ «{», начинающий вложенные инструкции, должен находиться в конце первой строки внешней инструкции;
Символы «{» и «}» должны обрамлять любые последовательности вложенных инструкций, в т.ч. и состоящие из одной инструкции;
Завершающий символ «}» составной инструкции должен располагаться на уровне первого символа первой строки составной инструкции.
Пример:
if (condition) {
namagerName=username[count];
count++;
} else {
return false;
}
Инструкции if, if-else, if else-if else
Инструкции категории if-else должны оформляться следующим образом:
if (condition) { //Наличие пары скобок обязательно(даже если один оператор)
statements;
}
if (condition) { //Наличие пары скобок обязательно(даже если один оператор)
statements;
} else {
statements;
}
if (condition) { //Наличие пары скобок обязательно(даже если один оператор)
statements;
} else if (condition) {
statements;
} else{
statements;
}
Инструкция for
Инструкция for оформляется следующим образом:
for (initialization; condition; update) {
statements;
}
Для пустой инструкции for следует использовать форму:
for (initialization; condition; update);
Инструкция while
Инструкция while оформляется следующим образом:
while (condition) {//Наличие пары скобок обязательно(даже если один оператор)
statements;
}
Для пустой инструкции while следует использовать форму:
while (condition);
Инструкция do-while
Инструкция for оформляется следующим образом:
do {
statements;
} while (condition);
Инструкция switch
Инструкция switch оформляется следующим образом:
switch (condition) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}
Инструкция try-catch
Инструкция try-catch оформляется следующим образом:
try {
statements;
} catch (ExceptionClass e) {
statements;
}
В случае использования finally:
try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}
Обработка ошибок
Для обработки ошибок следует использовать механизм Exceptions (см. п. Инструкция try-catch)
Доступ к методам и переменным
Доступ к атрибутам класса
Не следует объявлять атрибуты класса как public без особых на то причин. Предпочтительно предоставлять доступ к атрибутам опосредовано через методы с именами, начинающимися с get для чтения значения атрибута и с set для установки нового значения.
Доступ к статическим методам и переменным
Следует избегать доступа к статическим методам и переменным через имя объекта и использовать для доступа имя класса.
Пример:
classMethod(); //OK
AClass.classMethod(); //OK
anObject.classMethod(); //НЕДОПУСТИМО
Константы
Числовые константы не следует использовать в непосредственной форме, за исключением –1, 0 и 1 в счетчиках циклов for.
Присваивание переменным
Следует избегать присваивания нескольким переменным в одной инструкции.
Пример:
fooBar.fChar = barFoo.lchar = 'c'; // НЕЖЕЛАТЕЛЬНО
Недопустимо использовать вложенные присваивания.
Пример:
d = (a = b + c) + r; // НЕДОПУСТИМО
Следует записать:
a = b + c;
d = a + r;
Оформление Java Server Pages (JSP)
В JSP не следует использовать Java-код непосредственно в JSP-файле. В место этого следует использовать технологию TagLibrary.
JSP-файл должен содержать только HTML-текст и JSP-теги (в т.ч. теги TagLibrary). Весь Java-код должен быть реализован как классы TagLibrary и находиться в отдельных Java-файлах, оформляемых в соответствии с данным стандартом.
JSP-теги оформляются в соответствии с общими правилами для HTML тегов, изложенными в Стандарте Кодирования на HTML.
Выполнение требований стандарта
Разрабатываемый в компании Java-код должен разрабатываться в соответствии с настоящим стандартом.
Выполнение требований данного стандарта обязательно для всех специалистов компании участвующих в разработке кода на Java.
Разрабатываемый программный Java-код может не соответствовать настоящему стандарту только в случае, если заказчик разрабатываемого решения предъявляет иные требования к оформлению программного кода. Решение о несоблюдении настоящего стандарта принимается руководителем проекта.
Контроль соответствия разрабатываемого кода настоящему стандарту
Контроль соответствия разрабатываемого кода настоящему стандарту осуществляется в процессе тестирования разрабатываемого решения в обязательном порядке, специалистами, осуществляющими тестирование решения.
Приложение А. Пример Java-кода
/*
* Copyright 2005-2006 ЗАО «Диасофт». All rights reserved.
*/
package ru.diasoft.blah;
import java.blah.blahdy.BlahBlah;
/**
* @author Andrey Ivanov
* @version $Revision: 1.19 $
*/
public class Blah extends SomeClass {
/* A class implementation comment can go here. */
/** classVar1 documentation comment */
public static int classVar1;
/**
* classVar2 documentation comment that happens to be
* more than one line long
*/
private static Object classVar2;
/** instanceVar1 documentation comment */
public Object instanceVar1;
/** instanceVar2 documentation comment */
protected int instanceVar2;
/** instanceVar3 documentation comment */
private Object[] instanceVar3;
/**
* ...constructor Blah documentation comment...
*/
public Blah() {
// ...implementation goes here...
}
/**
* ...method doSomething documentation comment...
*/
public void doSomething() {
// ...implementation goes here...
}
/**
* ...method doSomethingElse documentation comment...
* @param someParam description
*/
public void doSomethingElse(Object someParam) {
// ...implementation goes here...
}
}
Москва
|
