GNUmakefile Предпочтительное имя для make-файлов. Мы используем gnumake для создания нашего программного обеспечения. gnumake для создания проектов Java? Муравей считается олдскулом, а мавен — Кто использует make для создания WAR, JAR, генерации JavaDocs …? 3.1.1 Начальные комментарии : Все исходные файлы должны начинаться с комментария в стиле c, в котором перечислены имя класса, информация о версии, дата и уведомление об авторских правах. Поместить имя класса в комментарий, начиная файл? Что если я передумаю и переименую класс позже? И что должна представлять эта « дата »? Некоторые люди используют различные заполнители для автоматической вставки времени последнего изменения файла системой контроля версий. Ну, VCS здесь, чтобы сказать вам, когда файл был создан или последний раз изменен — и изменение одной и той же строки снова и снова делает слияние огромной болью. 4 — Отступ : в качестве единицы отступа должны использоваться четыре пробела. Точная конструкция отступа (пробелы и табуляции) не указана. Вкладки должны быть установлены точно каждые 8 пробелов (не 4). Вероятно, самая нелогичная часть документа. Некоторые предпочитают пробелы, другие (в том числе и я) — вкладки. Дело вкуса и командных договоренностей. Но это руководство предлагает использовать и то, и другое, иногда заменять пробелы символами табуляции. Это « не указано ». Мой совет: используйте вкладки и дайте каждому разработчику настроить его IDE так, чтобы он имел как можно большие, так и маленькие отступы.
Избегайте строк длиной более 80 символов, так как они плохо обрабатываются многими терминалами и инструментами.
80 символов? Мой ноутбук легко помещается в три раза больше. Стремитесь к 120-140 символам в одной строке, но не используйте жесткие переносы. Лично я просто отображаю вертикальное поле и
длина правой строки определяется читабельностью. Кстати, вот несколько примеров классов из различных библиотек и фреймворков:
-
SQLIntegrityConstraintViolationException(JDK 7, 40 символов) -
AbstractInterruptibleBatchPreparedStatementSetter(среда Spring, 50 символов) -
AbstractDataSourceBasedMultiTenantConnectionProviderImpl(Hibernate, 56 символов) -
PreAuthenticatedGrantedAuthoritiesWebAuthenticationDetails(Spring Security, 58 символов)
И мы должны вписать всю строку в 80 символов?
5.1.2 Однострочные комментарии :
|
1
2
3
4
5
|
if (condition) { /* Handle the condition. */ ...} |
На случай, если код недостаточно информативен, я предлагаю еще лучший комментарий:
|
1
2
3
4
5
|
if (condition) { /* This block is executed if condition == true. */ ...} |
|
1
2
3
4
5
|
if (a == 2) { return TRUE; /* special case */} else { return isPrime(a); /* works only for odd a */} |
Вы имели в виду (и не говорите мне, что это менее читабельно, даже без комментариев)?
|
1
|
return a == 2 || isPrime(a); |
|
1
2
|
int level; // indentation levelint size; // size of table |
Зачем использовать описательные имена переменных, когда у нас есть комментарии ! Рассмотрим это вместо этого:
|
1
2
|
int indentationLevel;int tableSize; |
Далее в этом разделе: ни в коем случае нельзя объявлять переменные и функции в одной строке. Пример:
|
1
|
long dbaddr, getDbaddr(); // WRONG! |
Конечно, это неправильно, он даже не компилируется. Я удивлен, что « не ставьте пробелы в именах переменных » не упоминается как хорошая практика…
Размещайте объявления только в начале блоков. […] Не ждите объявления переменных до их первого использования; это может запутать неосторожного программиста […] Вот как соглашения о кодировании хотят, чтобы вы писали свой код:
|
01
02
03
04
05
06
07
08
09
10
|
int min; //inclusiveint max; //exclusiveint distance;List<String> list; //one per each itemmin = findMin();max = findMax();distance = max - min;list = new ArrayList<>(distance);//... |
И вот как это должно быть написано, чтобы избежать путаницы:
|
1
2
3
4
5
|
final int minInclusive = findMin();final int maxExclusive = findMax();final int distance = maxExclusive - minInclusive;final List<String> listOfItems = new ArrayList<>(distance);//... |
Кроме того, мы можем, наконец, ( nomen est omen ) использовать ключевое слово final . Далее в этом разделе приведен пример кода с полями класса, в которых отсутствует private модификатор (по умолчанию, закрытый доступ к пакету). Пакет приватного поля?
|
1
|
return (size ? size : defaultSize); |
Возможно, вы не заметили, но из контекста мы можем сказать, что и size и defaultSize имеют boolean тип. Правильно, size и defaultSize могут быть как true и false (!) Как это нелогично! От такого документа я бы ожидал не только синтаксической правильности, но и значимого кода и хороших практик! Более того, выражение может быть значительно упрощено, шаг за шагом :
|
1
2
3
|
size ? size : defaultSizesize ? true : defaultSizesize || defaultSize |
Пустой оператор for (в котором вся работа выполняется в предложениях инициализации, условия и обновления) должен иметь следующую форму:
|
1
|
for (initialization; condition; update); |
‘
пусто for выписки ? Зачем вам когда-либо использовать пустое for заявления? Это сбивает с толку, и его следует избегать, а не поощрять и описывать в официальном руководстве по языку.
Бонус викторина: какова цель этого кода в C?
|
1
|
while(*dst++ = *src++); |
Я считаю, что каждый программист должен понимать фрагмент кода выше. Даже если вы программируете на Ruby или TSQL.
Каждый раз, когда case проваливается (не содержит оператора break ), добавьте комментарий там, где обычно был бы оператор break .
Я понимаю намерения, но подход неверен. Вместо того, чтобы документировать неожиданные и подверженные ошибкам фрагменты кода, просто избегайте их. Не зависите от провала, не используйте его вообще.
Одна пустая строка всегда должна использоваться при следующих обстоятельствах:
[…]
- Между локальными переменными в методе и его первым оператором
- Перед блоком […] или однострочным комментарием […]
- Между логическими разделами внутри метода для улучшения читабельности
Похоже, авторы предлагают использовать пустые строки для разделения « логических разделов метода ». Ну, я называю эти разделы: « методы ». Не группируйте операторы внутри методов в блоках, комментируйте их и отделяйте друг от друга. Вместо этого извлеките их в отдельные, хорошо названные методы!
Размещение пустой строки между объявлениями переменных и первым оператором звучит так, как будто они взяты из книги по языку Си.
- Все бинарные операторы, кроме
.должны быть отделены от своих операндов пробелами. Пробелы никогда не должны отделять унарные операторы, такие как унарный минус, приращение (‘++‘) и декремент (‘--‘), от их операндов. Пример:
[…]
|
1
2
3
|
while (d++ = s++) { n++;} |
Это даже не компилируется в Java …
9 — Соглашения об именах (только в PDF-версии ):
|
1
|
char *cp; |
Хорошее имя для указателя на char в Java — cp . Подожди, ЧТО ? указатель на char в Java?
10.1 Предоставление доступа к переменным экземпляра и класса :
Не делайте ни один экземпляр или переменную класса общедоступным без уважительной причины. Действительно, действительно хорошая причина! Я когда-либо использовал public поле?
|
1
2
3
|
if (c++ = d++) { // AVOID! (Java disallows) ...} |
Хороший совет: пожалуйста, избегайте использования конструкций, которые даже не компилируются в Java. Это делает нашу жизнь намного проще!
10.5.2 Возвращаемые значения :
|
1
2
3
4
5
|
if (booleanExpression) { return true;} else { return false;} |
вместо этого должно быть написано как
|
1
|
return booleanExpression; |
Святая корова, я согласен!
Резюме
Дело не в том, что официальные соглашения о коде для языка программирования Java полностью неверны. Они просто устарели и устарели. Во втором десятилетии XXI века у нас лучшее оборудование, более глубокое понимание качества кода и более современные источники мудрости . Соглашения о коде … в последний раз были опубликованы в 1999 году, они основаны на языке C и не знают о миллиардах строк кода, которые еще предстоит написать миллионам разработчиков. Соглашения о коде должны появляться со временем, точно так же, как шаблоны проектирования, а не передаваться явно. Поэтому, пожалуйста, не цитируйте и не следуйте советам официального руководства.
Ссылка: Соглашения о кодировании Java, считающиеся вредоносными, от нашего партнера по JCG Томаша Нуркевича в блоге, посвященном Java и соседству .