Соглашения об оформлении кода
- Использовать автоформат из IDE. (TODO узнать отличия автоформата в NetBeans).
В IntelliJ IDEA: Ставить галочки "Форматировать код" и "Оптимизировать импорты" перед коммитом:
- Не использовать wildcards в секции импортов.
Причина: исключение конфликтных ситуаций при использовании классов с одинаковыми именами, но относящимися к разным пакетам.
В IntelliJ IDEA:
- Избегайте строки длиннее 80 символов, так как они плохо обрабатываются многими терминалами и инструментами. Если выражение не умещается в одну строку, разбейте его, руководствуясь следующими основными принципами:
- Перенос после запятой
- Перенос перед оператором
- Предпочитаются переносы на более высоком уровне переносам на низком (более вложенном) уровне.
- Выравнивайте новую строку выражения так, чтобы его начало было на том же уровне как и в предыдущей строке.
- Если приведенные выше правила приводят к сбивающему с толку коду или коду, который жмется к полям справа, просто сделайте вместо этого отступ в 8 пробелов.
- Пробелы
Пустые строки улучшают читабельность выделенных участков кода, которые логически связаны между собой. Две пустые строки всегда должны использоваться в следующих случаях:
- Между секциями в файле исходного кода
- Между определениями класса и интерфейса
Одна пустая строка всегда должна использоваться в следующих случаях:
- Между методами
- Между локальными переменными метода и его первым оператором
- Перед блочным или однострочным комментарием
- Между логическими участками кода внутри метода для улучшения читабельности
Разделяющие пробелы должны ставиться при следующих обстоятельствах:
- Ключевое слово и следующие за ним скобки должны быть разделены пробелом.
Заметьте, что разделяющий пробел не используется между именем метода и его открывающей скобкой. Это помогает отличить ключевое слово от вызова функции.
- Разделяющий пробел должен появляться после запятой в списке аргументов.
- Все бинарные операции должны быть отделены от их операндов пробелами. Разделяющие пробелы никогда не отделяют унарные операторы, такие как унарный минус, инкремент ("++") и декремент ("--") от их операндов.
- Выражения в операторе for должны быть разделены пробелами.
- За приведением типа должен следовать пробел.
- Комментарии в Java делятся на 2 вида: комментарии реализации и документирующие комментарии. Комментарии реализации те же, что и в C++, обозначаются /* ... / и //. Документирующие комментарии (известные как "doc comments" или "Javadoc") есть только в Java, и обозначаются /* ... */. Javadoc может быть извлечен из кода в HTML файл, используя инструмент javadoc.
Комментарии кода используются для описания отдельных строк/блоков кода или целого алгоритма. Комментарии для документирования используются, чтобы описать спецификацию кода, не зависящую от его реализации.
Комментарий можно считать полезным, если:
- достаточно прочитать 6 строк комментария вместо 80 строк кода метода с бизнес-логикой;
- в комментарии дается ссылка на реализуемый малоизвестный алгоритм или структуру данных (например — «для поиска подстроки используется алгоритм Ахо — Корасик», ссылка на википедию или спец. сайт);
- комментарий поясняет, почему автор использует не тот подход, который читающий код скорее всего ожидает тут увидеть (например, написанный руками SQL запрос вместо работы через ORM фреймворк, или почему для поиска в XML используется regexp, а не XPath);
- в комментарии дан короткий ясный пример использования.
Не стоит делать огромных комментариев, отделенных от основного кода строками из "*" или других символов. Комментарии не должны содержать специальных символов, таких как символ конца страницы или backspace.
- Наименования
Имена классов пишутся в UpperCamelCase.
Имена переменных, методов пишутся в lowerCamelCase
Константы - CONSTANT_CASE
Из наименований должны быть понятны предназначения объектов.
Ни в коем случае не использовать транслит, в качестве наименований должны использоваться английские слова.
- Объявления
МОЖНО:
- Рекомендуется использовать одно объявление на строку, так как это облегчает комментирование.
- Размещайте объявления только в начале блоков (блоком является любой код, заключенный в фигурные скобки "{"" и "}"). Не ждите объявления переменных до их первого использования; Это может запутать неопытного программиста и затруднить переносимость кода в пределах области. Единственным исключением из этого правила являются индексы циклов for, которые в Java могут быть объявлены в операторе for
НЕЛЬЗЯ:
- Ни в коем случае нельзя объявлять переменные и функции в одной строке.
- Не помещайте переменные разных типов (имеется в виду не тип самих переменных, а тип данных которые в них хранятся) в одну строку.
- Избегайте локальных объявлений, перекрывающих объявления более высокого уровня. Например, не объявляйте одну и ту же переменную перед блоком кода и во внутреннем блоке.
Старайтесь инициализировать локальные переменные там, где вы их объявляете. Единственная причина не инициализировать переменную в месте её объявления — если её начальное значение зависит от некоторых предварительных вычислений.
- Операторы
8.1. Простые операторы
Каждая строка должна содержать не более одного оператора. Не используйте запятую для группировки нескольких операторов, даже если это видно невооруженным глазом.
8.2. Составные операторы
Составные операторы - это операторы, содержащие списки операторов, заключенные в фигурные скобки "{ операторы }".
- Вложенные операторы должны иметь отступ на один уровень больше, чем составной оператор.
- Открывающая скобка должна быть в конце той строки, с которой начинается составной оператор; закрывающая скобка должна начинаться с новой строки и с отступом, соответствующим началу составного оператора.
- Скобки используются во всех операторах, даже в одиночных, когда они входят в состав управляющей структуры, таких, как оператор if-else или for. Это необходимо, чтобы избежать ошибок в случае добавления новых операторов, когда забыли указать фигурные скобки (если фигурных скобок нет, то управляющая конструкция типа if будет выполнять только одну строку после нее до знака ";").
8.3. Оператор return
Оператор return, возвращающий значение, не должен использовать скобки, если только их использование не сделает возвращаемое значение более понятным.
Форматирование steam https://marcin-chwedczuk.github.io/java-streams-best-practices