Конвенции кодирования на Java

1. Конвенции кодирования на Java

Code Conventions for Java

2. Зачем нужны конвенции кодирования

Хороший стиль
Конвенции разработаны на основе опыта
многих программистов
Чтение кода
Не нужно привыкать к чужому коду
Модификация кода
Каждый может вносить изменения, не
перестраиваясь

3. Code Conventions for Java

http://java.sun.com/docs/codeconv/
Разработан специально для Java
Разработчик – Sun Microsystems
Единый стандарт
Соблюдают не все, но большинство
Поддерживается средами разработки

4. Структура CCJ

Имена файлов
Организация файла
Отступы
Комментарии
Декларации
Предложения языка (statements)
Пустое место (white space)
Конвенции именования
Идиомы (programming practices)

5. Имена файлов

Расширения:
Файлы с исходным кодом: *.java
Файлы с байт-кодом: *.class

6. Организация файла

Файл разделяется на секции
Секции отделяются друг от друга пустой
строкой и, возможно, комментарием
Размер файла не должен превосходить
2000 строк

7. Организация файла - классы

В одном файле может находиться
только один public-класс (интерфейс)
Допускается размещение в том же
файле других классов, логически
связанных с основным
Основной класс должен быть первым в
файле

8. Организация файла - секции

Начальный комментарий
/*
* Classname
* Version information
* Date
* Copyright notice
*/
Пакет и импорты
package java.awt;
import java.awt.peer.CanvasPeer;

9. Организация файла – структура класса

JavaDoc-комментарий (/** */)
Заголовок класса
Комментарий к реализации (/*
Статические поля
Нестатические поля
Конструкторы
Методы
*/)

10. Отступы

Единица отступа – 4 пробела
допустима и табуляция
Длина строки – не более 80 символов
иначе может не влезать на экран
Перенос
после запятой
перед оператором
отступает от исходной строки

11. Комментарии

Блочный комментарий
/*
* Here is a block comment.
*/
Однострочный комментарий (/* */)
/* Do something */
doIt();
Однострочный комментарий (//)
// Do something
doIt();
return true; // Why here
JavaDoc-комментарий
классы/интерфейсы
public и protected методы и поля

12. Декларации

Одна декларация на строке
int
int
a, b; // плохо
a;
int b; // лучше
Инициализация на месте
int
a = 239; // еще лучше
Размещение
Как можно ближе к месту использования
Область видимости - как можно более узкая
Повторение имен
Одно имя не должно закрывать другое:
переменная и поле

13. Декларации членов класса

Пробел между именем метода и «(» не ставится
void doIt()
Фигурная скобка «{» ставится на той же строке через
пробел
void doIt() {
Фигурная скобка «}» начинает новую строку на том
же уровне, что и заголовок метода
void doIt() {
// ...
}
Декларации методов разделяются пустыми строками

14. Предложения языка (statements)

Простые предложения
a++;
b++; // хорошо
a++; b++; // плохо
Сложные предложения – { … }
Содержимое отступает на один уровень
Скобки – как для методов
Операторные скобки используются для ВСЕХ структурных
операторов: if-else, while, do-while, for, switch
if (condition) {
doIt(); // даже если тело состоит из 1 строки
}

15. Предложение return

Скобки вокруг возвращаемого
выражения обычно не ставятся
return
disk.getSize();

16. Предложение if

if (condition) {
statements;
}
if (condition) {
statements;
} else {
statements;
}

17. Предложение if – каскад

if (condition) {
statements;
} else if (condition) {
statements;
} else {
statements;
}

18. Еще раз: скобки

Не делайте так:
if (condition)
statement;
Делайте так:
if (condition) {
statement;
}

19. Циклы for

for (initialization; condition; update) {
statements;
}
for (initialization; condition; update);

20. Циклы while

while (condition) {
statements;
}
while (condition);
do {
statements;
} while (condition);

21. Предложение switch

switch (condition) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}

22. Предложение try-catch

try {
statements;
} catch (ExceptionClass e) {
statements;
}

23. Предложение try-catch-finally

try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}

24. Пустое место - строки

Пустые строки
две строки разделяют
объявления классов/интерфейсов
одна строка
между методами
перед комментарием
между секциями кода внутри метода

25. Пустое место - пробелы

Между ключевым словом и скобкой
while (condition) {
После запятой в списке параметров
doIt(a, b, c);
Вокруг бинарной операции (кроме «.»)
a += b + c;
После «;» в заголовке for
for (int i = 0; i < 5; i++)
После операции приведения типа
(int) value

26. Пустое место – нет пробелов

Между именем метода и скобкой
doIt(a, b, c);
Перед/после унарной операции
a++;
--b;

27. Конвенции именования

По имени должно быть ясно, что мы
видим перед собой:
ru.amse.mypackage – пакет
MyClass – класс/интерфейс
run(), doSomething() – метод
i, myValue – поле/переменная
THE_CONSTANT – константа
Thing,

28. Идиомы

Сокрытие полей
Вызов статических методов
classMethod();
// хорошо
AClass.classMethod(); // хорошо
anObject.classMethod(); // плохо
Использование именованных констант
-1, 0, 1 – допустимы

29. Идиомы – присваивания

Избегать каскадных присваиваний
fooBar.fChar
= barFoo.lchar = 'c';
Не использовать «=» там, где его легко
спутать с «==»
if
(c = d) {
Не злоупотреблять возвращаемым
значением
d
= (a = b + c) + r;

30. Идиомы – скобки

Использовать скобки в условиях
if
(a == b && c == d) {
if ((a == b) && (c == d)) {
Использовать скобки в тернарном
операторе
(x
>= 0) ? x : -x;

31. Идиомы – возврат значения

if
(booleanExpression) {
return true;
} else {
return false;
}
return booleanExpression
if (condition) {
return x;
}
return y;
return (condition ? x : y);

32. Code Conventions for Java

http://java.sun.com/docs/codeconv/