Лекция
Привет, сегодня поговорим про оформление кода java, обещаю рассказать все что знаю. Для того чтобы лучше понимать что такое оформление кода java, java code conventions , настоятельно рекомендую прочитать все из категории Разработка программного обеспечения и информационных систем.
При написании программы на любом языке следует придерживаться какого-нибудь соглашения об оформлении кода. Соглашение, или стандарт, описывает, где и как надо ставить переносы строк, какие отступы делать для блоков кода, и так далее.
Если поначалу кажется, что оформление кода по стандарту - не так уж важно, то скажу следующее: около 80% времени работы над программой составляет поддержка. То есть, 80% уходит на поиск ошибок, на мелкие исправления и добавления новых функций. Другими словами, 80% времени приходится копаться в существующем коде. А программный код средних и больших проектов почти наверняка будет обслуживаться уже не одним человеком, а по крайней мере несколькими.
Поэтому так важно, чтобы каждый программист в отдельности придерживался одного стандарта оформления, принятого в данной команде разработчиков. Если же ваша "команда" состоит лишь из одного человека, то даже в этом случае необходимо придерживаться стандартов, ведь по прошествии времени самому придется возвращаться к старому коду, пытаясь вспомнить, как он работает.
Сравните два отрывка одного и того же кода, оформленного по-разному. Один из них оформлен абы-как, а другой (угадайте, какой :)) - с использованием соглашения об оформлении кода "Java Coding Conventions". Какой из них проще понять?
public String toString() {
int len = this.end - 0;
char[] ss = new char[len];
for (int i = 0; i < len; i++) {
ss[i] = this.cc[this.cci[i]];
}
return String.valueOf(ss);
}
public String toString()
{
int len=this.end; char[] ss=new char[len];
for(int i=0;i
Почти в каждой крупной организации или группе разработчиков есть свой стандарт оформления кода. Один из стандартов, предложенный Sun для программирования на Java - "Java Code Conventions", следуя которому, получается весьма компактный, но в то же время прекрасно читаемый код. Java Code Conventions во многом применимы и для других языков, например, PHP.
В программном коде для отступов Java Code Conventions разрешает использовать как пробелы, так и символы табуляции. Однако, практика показывает, что отступы пробелами более "надежны" в смысле переносимости кода. Например, код, отформатированный только пробелами, можно переносить из одного проекта в другой без потери форматирования, даже если в настройках разных проектов размер символа табуляции задан разный.
Во многих средах разработки по умолчанию сконфигурирован размер символа табуляции, равный четырем пробелам. Это, я убежден, в корне ошибочно. Исторически, символ табуляции занимает 8 пробелов от начала строки. Когда редактор вместо 4 пробелов ставит в файле символ табуляции, то открыв этот же файл любым другим редактором, отображающим "стандартные" 8 символов на табуляцию, получим свалку неформатированного кода.
Это аукнется, когда изменения в программу придется вносить не любимым редактором в любимой тонко настроенной IDE, а каким-нибудь Far или обычным блокнотом, в полевых условиях.
Существует так называемая "венгерская нотация", предписывающая давать названия переменным и членам классов с использованием префиксов, указывающих на тип переменной, например:
int m_iCount; LPCTSTR m_lpszName;
Польза венгерской нотации - под вопросом, поскольку типы переменных могут часто меняться, особенно при активной разработке, да и вводить каждый раз конструкции вроде "m_lpszName" вместо "name" - удовольствие сомнительное.
В случае командной работы над проектом, какие бы ни были выбраны соглашения об отступах, переносах строки и прочих нюансах оформления кода, их по возможности следует хранить в свойствах проекта, чтобы при использовании системы управления версиями (SVN, GIT) эти настройки автоматически оказались бы у каждого разработчика.
В Eclipse довольно тонкие настройки форматирования можно задать как на уровне Workspace, так и в самом проекте. В случае совместной работы, настройки следует делать именно в проекте.
В идеале, стандарт оформления кода должен обеспечиваться самой средой разработки. Если нет внешних факторов, навязывающих какие-то особенности оформления, то все настройки его можно сконфигурировать в IDE, в которой вы работаете. Современные среды разработки умеют форматировать исходный код в соответствии с указанными настройками. Это позволяет не заморачиваться на форматировании, а дать команду IDE самой отформатировать код. Это можно сделать как для небольшого фрагмента, так и для всего файла. Автоформатирование средствами IDE - очень полезная возможность, которой следует пользоваться.
Обычно форматирование исходника вызывается правым кликом по тексту программы в IDE, а дальше - выбираем пункт в выпадающем меню. Например, в NetBeans - Format.
При командной работе настройки форматирования должны быть доступны через систему управления исходниками всем членам команды, поэтому и автоформатирование будет давать одинаковый результат.
***
Соглашения по оформлению кода Java
1. Введение
Соглашения по коду важны для программистов по ряду причин:
• 80% расхода времени при использовании компонента программного обеспечения уходит на его обслуживание.
• Редко программа поддерживается в течение всей своей жизни первым автором.
• Соглашение по коду улучшает читаемость программного обеспечения, что позволяет инженерам понимать новый код более быстро и детально.
• Если вы поставляете ваш код как продукт, нужно убедиться, что он так же хорошо сгруппирован и чист, как и любой другой продукт, который вы создаете.
Этот документ отражает стандарты написания кода на языке Java представленные в Java Language Specification, от Sun Microsystems, Inc. Спасибо Peter King, Patrick Naughton, Mike DeMoney, Jonni Kanerva, Kathy Walrath, и Scott Hommel.
По вопросам адаптации, модификации или распространение этого документа, пожалуйста, прочтите наше уведомление об авторских правах на http://java.sun.com/docs/codeconv/html/Copyright.doc.html.
Комментарии к этому документу должны быть представлены в форму обратной связи на http://java.sun.com/docs/forms/sendusmail.html.
В этом разделе перечислены часто используемые файловые суффиксы и имена.
JavaSoft использует следующие расширения файлов:
Тип файла |Расширение
-----------------------
Исходный Java-код |.java
Java-байткод |.class
Часто используемые имена для файлов включают в себя:
Имя файла | Использование
-----------------------
GNUmakefile | Предпочтительное имя для make-файлов. Мы используем gnumake для сборки нашего программного обеспечения.
README | Предпочтительное имя файла, который суммирует содержимое определенного каталога.
Файл состоит из разделов, которые должны разделяться пустыми строками и необязательными комментариями, определяющими каждый раздел.
Файлы длиннее 2000 строк громоздки и их следует избегать.
В качестве примера правильного оформления Java программы, см. "Java Source File Example" на стр. 19.
Каждый исходный Java файл содержит один public класс или интерфейс. Когда private классы и интерфейсы связанны с public классом, вы можете поместить их в тот же исходный файл что и public класс. Public класс должен быть первым классом или интерфейсом в файле.
Исходные Java файлы имеют следующую структуру:
* Открывающие комментарии (см. "Открывающие комментарии" на стр. 4)
* Сведения о пакете и импорте; например:
import java.applet.Applet;
import java.awt.*;
import java.net.*;
* Объявление классов и интерфейсов (см "Объявление классов и интерфейсов" на стр. 4)
3.1.1. Открывающие комментарии
Все файлы исходники должны начинаться с комментария в стиле С, который дает список программиста(ов), дату, авторские права, а также краткое описание назначения программы. Например:
/*
* Имя класа
*
Информация о версии
*
* Примечание к копирайту
*/
Первая строка не-комментарий в большинстве исходников Java это сведения о пакете, после чего идут сведения о импорте. Например:
package java.awt;
import java.awt.peer.CanvasPeer;
3.1.3 Объявление классов и интерфейсов
Приведенная ниже таблица описывает объявление части класса или интерфейса в порядке их появления. См. "Пример файла исходника Java" на стр. 19 для примера с комментариями.
|объявление части класса / интерфейса | примечания
-----------------------------------------------------------------------------------
1 | Комментарии к документации класса/интерфейса (/**...*/) | Смотрите “Комментарии к документации” на стр. 9 с информацией о том, что должно быть в этом комментарии.
2 | Операторы class или interface
3 | Комментарии о реализации класса/интерфейса (/*...*/), если необходимо | Эти комментарии должны содержать расширенную информацию о классе/интерфейсе, которая не относится к комментариям документации класса/интерфейса
4 | Статические переменные класса | Сначала public переменные класса, затем protected, затем пакетные (без спецификатора доступа) и затем private.
5 | Не статические переменные | Сначала public, затем protected, затем пакетные (без спецификатора доступа) и затем private.
6 | Конструкторы
7 | Методы | Эти методы должны группироваться больше по функциональности чем по области видимости или доступности. Например, private метод класса может быть между двумя случайными public методами. Цель – сделать чтение и понимание кода проще.
Отступы
Один отступ должен содержать четыре пробела. Точный формат отступа (пробелы или знаки табуляции) не задан. Табуляция должна содержать 8 пробелов (не 4).
Избегайте строк длиннее 80 символов, потому что они могут быть некорректно восприняты многими терминалами и другими устройствами.
Замечание: для примеров, использующихся в документации, длина строки должна быть меньше - обычно не более 70 символов.
Переносы строк
В случах, кода выражение не входит на одну строку, сделайте переход на другую в соотвествии с этими общими принципами:
Несколько примеров переноса строк для вызовов методов:
function(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);
var = function1(longExpression1,
function2(longExpression2,
longExpression3));
Ниже приведены примеры переноса строк для арифметических выражений. Первый вариант предпочтительнее, так как перенос делается после выражения в скобках, то есть на более высоком уровне.
longName1 = longName2 * (longName3 + longName4 - longName5)
+ 4 * longname6; // Лучше
longName1 = longName2 * (longName3 + longName4
- longName5) + 4 * longname6; // Хуже
Далее приведены два примера переноса строк в определении метода. Первый использует соглашения. Во втором использование соглашений привело бы к тому, что вторая и третья строка были бы слишком сдвинуты вправо, поэтому используется только отступ в 8 пробелов.
// СОГЛАШЕНИЕ ПО ОТСТУПАМ
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}
// ДЕЛАЙТЕ ОТСТУП В 8 СИМВОЛОВ ДЛЯ ИЗБЕЖАНИЯ ГЛУБОКОЙ ВЛОЖЕННОСТИ
private static synchronized horkingLongMethodName(int anArg,
Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
...
}
Оформление строк для выражения if должно использовать 8-символьный отступ, т.к. использование стандартного (4-символьного) затрудняет просмотр тела выражения. Например:
// ТАК ОТСТУПЫ ДЕЛАТЬ НЕЛЬЗЯ
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) { //ПЛОХОЕ ОФОРМЛЕНИЕ
doSomethingAboutIt(); // ПОЗВОЛЯЕТ ЛЕГКО ПРОПУСТИТЬ ЭТУ СТРОКУ
}
// ЛУЧШЕ ОТСТУПЫ ДЕЛАТЬ ВОТ ТАК
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
// ИЛИ ВОТ ТАК
if ((condition1 && condition2) || (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
Ниже приведены три приемлемых способа форматирования тернарных выражений:
alpha = (aLongBooleanExpression) ? beta : gamma;
alpha = (aLongBooleanExpression) ? beta
: gamma;
alpha = (aLongBooleanExpression)
? beta
: gamma;
У Java программ могут быть два вида комментариев: комментарии реализации и комментарии документации. Комментарии реализации, аналогичные комментариям в C++, ограничиваются /*...*/ и //. Комментарии документации (известные как “doc comments”) встречаются только в Java и ограничиваются / **...*/. На основе документирующих комментариев с помощью утилиты javadoc могут быть созданы файлы документации в формате HTML.
Комментарии реализации - средства для того, чтобы прокомментировать код или особенности реализации. Комментарии документации предназначены для описания характеристик кода не зависящих от реализации, чтобы в будущем могли быть прочитанными разработчиком, у которого не обязательно будет под рукой исходный код.
Комментарии должны использоваться, чтобы дать краткий обзор кода и предоставить дополнительную информацию, которую нельзя легко получить из кода непосредственно. Комментарии должны содержать только информацию, которая относится к чтению и пониманию программы. Например, информация о том, как соответствующий пакет построен, или о том, в какой директории он находится, не должна быть включена как комментарий.
Пояснение нетривиальных или неочевидных проектных решений допускается, но следует избегать дублирование информации, которая присутствует в коде (и понятна из него). Избыточные комментарии быстро устаревают. Вообще, избегайте любых комментариев, которые, скорее всего, устареют при развитии кода.
Замечание: Частота комментариев иногда отражает низкое качество кода. Если Вы почувствуете, что нужно добавить еще комментариев, подумайте, вероятно нужно переписать такой код, что бы сделать его более понятным.
Комментарии не должны быть вложены в большие блоки, со звездочками или другими символами.
Комментарии никогда не должны включать служебные символы, такие как возврат каретки и backspace.
Программа может содержать такие стили комментариев реализации, как: "блочный", "однострочный" или "комментарий в конце строки"
Блочные комментарии используются для описания файлов, методов, структур данных и алгоритмов. Блочный комментарий должен присутствовать в начале каждого файла и перед каждым методом. Также их можно использовать и в других местах: например, внутри методов. Блочный комментарий внутри функции или метода должен быть выровнен по уровню комментированного кода.
Для отделения от остального кода блочный комментарий должен предваряться пустой строкой. Каждая строка блочного комментария, кроме первой, должна начинаться с символа "звездочки" ("*").
/*
* Это блочный комментарий
*/
Блочный комментарий начинается с "/*". Оформление тела комментария не должно изменяться. Пример:
/*
* Это блочный комментарий с весьма специфичным
* оформлением, в котором не используются отступы
*
* один
* два
* три
*/
Замечание: Если вы используете отступы, то и блочный комментарий не используйте или пойдите на уступки чтобы другие могли прибегнуть к идентации вашего кода.
См. "Документирующий комментарий" на стр. 9.
Короткий комментарий можно разместить на одной строке, выровненой по уровню следующего за ним кодом. Если комментарий не умещается на одной строке, его нужно записать как блочный комментарий(смотри раздел 5.1.1). Перед однострочным комментарием стоит оставить пустую строку. Вот пример кода с однострочным комментарием (см. также "Документирующие комментарии" на стр. 9):
if (условие) {
/* Обработка условия */
...
}
Очень короткие комментарии могут стоять на одной строке с комментируемым кодом, но должны быть отделены от него отступом. Если таких комментариев в фрагменте кода больше одного они должны быть выровнены по одному уровню. Избегайте комментирования, как в ассемблере, в конце каждой строки исполняемого кода.
Вот пример кода с блочным комментарием в конце строки (см. также "Документирующие комментарии" на стр. 9)
return TRUE; /* исключение */
return isprime(a); /* только для нечетной a */
"//" - знак означающий начало однострочного комментария в плоть до конца строки. Он может занимать всю строку или только ее часть. Не стоит использовать однострочный комментарий для многострочного текста; однако, так можно закомментировать часть кода. Пример всех трех стилей:
// Делаем двойной перевот
return false; // Объясняю почему здесь.
// // Делаем тройной переворот.
Документирующие комментарии применяются при описании классов , интерфейсов, конструкторов, методов и полей. Каждый документирующий комментарий заключается в /**...*/ и относится только к какому-то одному конкретному элементу API. Этот комментарий должен предшествовать элементу, для которого делается описание:
выражение ;
} else if (условие) {
выражение ;
}
выражение;
for (инициализация; условие; обновление) {
выражение;
}
for (инициализация; условие; обновление);
while (условие) {
выражение;
}
while (условие);
do {
выражение;
} while (условие);
switch (условие) {
case ABC:
выражение;
case DEF:
выражение;
break;
case XYZ:
выражение;
break;
default:
выражение;
break;
}
try {
выражение;
} catch (ExceptionClass e) {
На этом все! Теперь вы знаете все про оформление кода java, Помните, что это теперь будет проще использовать на практике. Надеюсь, что теперь ты понял что такое оформление кода java, java code conventions и для чего все это нужно, а если не понял, или есть замечания, то не стесняйся, пиши или спрашивай в комментариях, с удовольствием отвечу. Для того чтобы глубже понять настоятельно рекомендую изучить всю информацию из категории Разработка программного обеспечения и информационных систем
Комментарии
Оставить комментарий
Разработка программного обеспечения и информационных систем
Термины: Разработка программного обеспечения и информационных систем