Java code conventions на русском

Такие правила приняты в нашей компании. Они позволяют делать код более читаемым и аккуратным, избегать ошибок, связанных с разными стилями написания кода у людей, работающих над проектом, и в будущем легко редактировать его.

Имена файлов, пакетов

  • В именах пакетов используются только строчные буквы.
  • Имена Java-классам даются согласно стандартной нотации Java.
  • Имена классов должны быть существительными, первые буквы всех слов — заглавные.
  • В именах web-папок и файлов используются только строчные буквы. Слова в многословных названиях разделяются подчеркиванием.

Имена методов, переменных

  • Названия методов должны быть глаголами, первая буква должна быть строчной, первые буквы внутренних слов — заглавные.
  • Имена переменных должны начинаться со строчной буквы, внутренние слова — с заглавной.
  • Имена констант составляются из всех заглавных букв, разделенных на слова символом подчеркивания.

Отступы, длина строки, переносы строк

  • Отступы должны составлять строго 4 пробела (не знак табуляции).
  • Длина строки не должна превышать 80 символов.
  • Если длина выражения превышает длину строки, то необходимо разбить его на несколько строк согласно следующим правилам:
    1. перенос после запятой;
    2. перенос перед оператором;
    3. необходимо использовать отступ 8 пробелов для обозначения второй строки разделенного выражения. Последующие строки выравниваются по второй строке либо добавляются новые 8 пробелов для обозначения вложенности.

    Расположение блоков, операторов, пробелы, скобки

    • Определение переменных нужно располагать в начале блока, а не «ждать» первого использования переменной. Инициализация должна производиться, по возможности, сразу.
    • Между именем метода и скобками для списка параметров нет пробела.
    • Параметры разделяются пробелом.
    • Пробелы окружают любой оператор.
    • Ключевое слово и следующая за ним скобка ( должны разделяться пробелом.
    • Открывающаяся скобка < располагается на той же строке, что и сигнатура метода/заголовок if, while-блока и т.п.
    • Закрывающаяся скобка > выровнена по строке начала данного блока.
    • Методы разделяются пустой строкой, объявления свойств класса располагаются по одному на строку.
    • На строке располагается только один оператор.

    Структурирование кода

    • Методы должны быть короткими, и выполнять только одну задачу (к примеру, почти любой цикл уже достоин того, чтобы вынести его в особый метод).
    • Имена методов должны быть самодокументированными.
    • Шаблоны ООП должны применяться для структурирования и облегчения восприятия.

    Стандарт разработан на основе “Code Conventions for the Java Programming Language” by Sun (http://java.sun.com/docs/codeconv/) с учетом принятых в коллективе практик.

    Читать далее

    Как мы работаем

    Гибким графиком ИТшников не удивить. В последние годы все больше крупных фирм предпочитают плавающий график работы фиксированному. Безусловно, очень удобно добираться на работу и с работы не в час пик, не тратя безумное количество времени и сил на дорогу, иметь возможность синхронизировать график работы со второй половиной… Мы в этом вопросе не являемся исключением. Гибкость […]

    ЛАР улетел в трубу

    Начнем, пожалуй, с главного — покажем короткое промо-видео, которое Google «скреативил» по нашему заказу , а затем расскажем, как это было. Кстати, добавляйтесь в круги команды ЛАР в Google+, ну или подписывайтесь на страницу в Facebook, как вам удобнее. Все мероприятие проходило в «Аэро» (стрелковый клуб «Медведь»), именно там с недавних пор стоит аэротруба. С информацией о стоимости, отзывами от […]

    Правила языка Java

    Правила Java библиотек

    Существуют соглашения, по поводу использования Java библиотек и инструментов для Android. В некоторых случаях соглашения могут быть изменены, например, в таких как использование старого кода, который, возможно, использует неодобренный паттерн или библиотеку.

    Правила Java стиля

    Программы гораздо проще поддерживать, когда все файлы имеют согласованный стиль. Мы следуем стандартному стилю программирования на Java, определенному Sun в их Code Conventions for the Java Programming Language, с несколькими исключениями и дополнениями. Данное руководство по стилю является подробным и всесторонним, а также широко используется Java сообществом.

    В дополнение, мы обязываем использовать следующие правила для кода:

    1. Комментарии/Javadoc: пишите их; используйте стандартный стиль.
    2. Короткие методы: не пишите гигантских методов.
    3. Поля: должны быть вверху файла, или прямо перед методом, который их использует.
    4. Локальные переменные: ограничивайте область видимости.
    5. Импорты: android; сторонние (в алфавитном порядке); java(x)
    6. Отступы: 4 пробела, без табуляций.
    7. Длина строки: 100 символов.
    8. Имена полей: не public и не static поля начинаются с «m».
    9. Фигурные скобки: открывающие фигурные скобки не находятся в отдельной строке.
    10. Аннотации: используйте стандартные аннотации.
    11. Сокращения: используйте сокращения как слова в именах, например, XmlHttpRequest, getUrl() и т.п.
    12. Стиль TODO: «TODO: пишите описание здесь».
    13. Согласованность: смотрите, что находится вокруг вас.

    Правила языка Java

    Не игнорируйте исключения

    Возможно, вам захочется написать код, который игнорирует исключения, например:

    Никогда так не делайте. В то время как вы думаете, что ваш код никогда не столкнется с таким условием или, что неважно обрабатывать это условие, игнорирование исключений создает скрытые проблемы. Вы в принципе должны обрабатывать каждое исключение. Специфика в каждом конкретном случае зависит от ситуации.
    Приемлимые альтернативы:

      Перебрасывайте исключения к вызывающему методу.

    Выбрасывайте исключения, соответственно вашему уровню абстракции

    Перехватите ошибку и замените соответствующее значение в блоке catch<>

  • Перехватите ошибку и выбросьте RuntimeException. Это опасно: делайте это только если вам все равно случится ли эта ошибка.
    Заметьте, что изначальное исключение передается конструктору RuntimeException. Если вы используете компилятор Java 1.3, то опустите исключение.
  • Если вы уверены в том, что игнорирование исключения в этом случае имеет место, то хотя бы прокомментируйте, почему вы так решили.
  • Не перехватывайте обобщенные исключения

    Иногда бывает заманчиво полениться с обработкой исключений и написать что-то вроде этого:

    Вам не следует так делать. Суть в том, что возможно появление исключения, которого вы не ожидали и, в итоге, ошибка будет отлавливаться на уровне приложения. То есть, если кто-то добавит новый тип исключения, то компилятор не сможет вам помочь понять, что это другая ошибка.

    Существуют редкие исключения из этого правила: определенный тестовый код, или код верхнего уровня, где вы хотите перехватывать все типы ошибок (для того, чтобы предотвратить их отображение в пользовательском интерфейсе, или чтобы продолжить какую-то пакетную задачу).

    Альтернативы обобщенным исключениям:

    • Перехватывайте каждое исключение отдельно в блоке catch, после одиночного try. Возможно это неудобно, но всё равно это предпочтительный способ для перехвата всех исключений.
    • Измените ваш код для более гранулированной обработки ошибок с несколькими блоками try. Отделите IO от парсинга, обрабатывайте ошибки отдельно в каждом случае.
    • Перебросьте исключение. Во многих случаях вам не нужно обрабатывать все исключения на текущем уровне, просто позвольте методу перебросить их.

    Помните: исключения — ваши друзья! Не сердитесь, когда компилятор указывает на то, что вы их не отлавливаете.

    Финализаторы

    Что это: Финализаторы — это способ запускать программный код перед тем как объект собирается сборщиком мусора.
    За: могут быть полезны при очистке, в особенности внешних ресурсов.
    Против: нет никаких гарантий того, когда будет вызван финализатор, и, вообще, будет ли он вызван.

    Решение: Мы не используем финализаторы. В большинстве случаев, всё то, что вам нужно от финализатора, вы сможете сделать при помощи обработки исключений. Если вам действительно нужен финализатор, то объявите метод close() и задокументируйте, когда он точно будет вызываться.

    Импорты
    Групповой символ в импортах

    Что это: Когда вы хотите использовать класс Bar из пакета foo, то есть два способа сделать это:

    За #1: Потенциально уменьшает количество возможных операторов импорта.
    За #2: Делает явным то, какой класс на самом деле используется. Делает код более удобочитаемым для тех, кто его поддерживает.

    Решение: Используйте стиль #2 для импорта любого Android кода. Явное исключение делается для стандартных библиотек (java.util.*, java.io.*, и т.п) и для кода модульного тестирования (junit.framework.*).

    Комментарии/Javadoc

    Каждый файл должен иметь объявление об авторских правах в самом начале. Далее идут объявления операторов package и import, причем каждый блок разделяется пустой строкой. За ними следуют объявления класса или интерфейса. Опишите, что делает класс в Javadoc-комментариях.

    Каждый класс и нетривиальный public метод должен содержать Javadoc, по крайней мере с одной фразой, описывающей что он делает. Фраза должна начинаться с описательного глагола 3-го лица. Примеры:

    Вам не нужно описывать Javadoc для тривиальных get и set методов, таких как setFoo(), если ваш Javadoc говорит только «sets Foo». Если метод делает что-то более сложное (например, соблюдение неких ограничений, или если его действия имеют важный эффект вне его самого), тогда его обязательно нужно задокументировать. И если это не просто объяснение того, что означает Foo, то вам также следует его задокументировать.

    Вообще, любой метод, который вы написали получает пользу от Javadoc, неважно public он или нет. Public методы являются частью API, и поэтому они требуют описания в Javadoc.

    Для написания Javadoc’ов вам следует придерживаться Sun Javadoc conventions.

    Короткие методы

    Методы должны быть небольшими и решающими конкретную задачу настолько, насколько это возможно. Однако, понятно, что иногда большие методы бывают целесообразны, так что нет строгого ограничения на длину метода. Если метод превышает 40 строк, то вам, возможно, стоит подумать о том, можно ли его разбить на части, не нарушив структуры программы.

    Локальные переменные

    Область видимости локальных переменных должна сводиться к минимуму. Делая это, вы улучшаете читаемость и поддерживаемость кода, а также уменьшаете вероятность ошибок. Каждая переменная должна объявляться в самом глубоком блоке, который окружает все возможные места использования переменной.

    Локальные переменные должны объявляться в том месте, где впервые необходимо её использовать. Почти каждая локальная переменная нуждается в инициализаторе. Если вы еще не знаете, как точно инициализировать переменную, то вам следует отложить её объявление, пока вы это не узнаете.

    Существует одно исключение, касательно блока try-catch. Если переменная инициализируется при помощи оператора return метода, который выбрасывает проверяемое исключение, то она должна инициализироваться в блоке try. Если же переменная должна использоваться вне блока try, тогда она объявляется перед ним, неважно, знаете ли вы как её точно нужно инициализировать:

    Но даже этот случай можно обойти при помощи инкапсуляции блока try-catch в методе.

    Переменные в циклах должны объявляться внутри самого оператора, если только нет непреодолимой причины этого не делать.

    Импорты

    Отступы

    мы используем 4 пробела для блоков. Мы никогда не используем табуляцию. Мы используем 8 пробелов для переноса строк, включая вызовы функций и присваивания, например правильно так:

    Названия полей

    • Не static и не public имена начинаются c «m».
    • static поля начинаются с «s».
    • Другие поля начинаются с буквы нижнего регистра.
    • Поля public static final (константы) пишутся полностью в верхнем регистре, с использованием подчеркивания (ALL_CAPS_WITH_UNDERSCORES)

    Например:

    Фигурные скобки

    Для открывающих фигурные скобок не выделяется отдельная строка, они находятся в той же строке, что и код перед ними:

    Мы требуем фигурные скобки для оператора условия. Исключением является, когда оператор условия и его тело помещаются в одну строку. То есть можно писать так:

    Длина строки

    Каждая строка текста в коде должна быть не длиннее 100 символов.
    Исключение: если комментарий содержит пример команд, или URL (удобнее использовать copy/paste).
    Исключение: строки импорта могут быть длиннее 100 символов, так как люди редко на них смотрят. Также это упрощает написание инструментов.

    Сокращения в именах

    Рассматривайте сокращения и аббревиатуры как слова. Имена более удобочитаемы:

    Хорошо Плохо
    XmlHttpRequest XMLHTTPRequest
    getCustomerId getCustomerID

    Этот стиль также применяется, когда сокращение и аббревиатура — это полное имя:

    Хорошо Плохо
    class Html class HTML
    String url; String URL;
    long id; long ID;

    Стиль TODO

    Используйте комментарии TODO для кода, который является временным, краткосрочным, или хорошим, но не идеальным. Комментарий должен включать в себя «TODO:», например:

    Если ваш комментарий имеет вид «В будущем сделать что-то», то убедитесь, что он включает в себя конкретную дату (1 января 2011 года), или конкретное событие «Удалить после выхода версии 2.1».

    Согласованность

    Если вы изменяете код, то потратьте минуту на то, чтобы посмотреть на код вокруг вас и определить его стиль. Если в нем используются пробелы, то и вам следует их использовать. Если комментарии содержат небольшой набор звездочек, то и вам следует их использовать.

    Весь смысл рекомендаций к стилю кода в создании общей лексики, чтобы люди концентрировались на том, что они говорят, вместо того как они говорят. Мы представляем глобальные правила стиля, чтобы люди знали эту лексику. Но локальный стиль также важен. Если код, который вы добавляете в файл выглядит резко отличным от того, что был, то это выбросит будущего читателя из его ритма и будет мешать ему понимать структуру. Старайтесь избегать этого.

    Материал из AOW

    Стайлгайд для Java

    Программы обычно пишутся прежде всего для человека, а уж потом для компьютера. Поэтому на читабельность программы и на то, чтобы она была понятной, надо обращать особое внимание. Неправильная, но понятная программа лучше правильной, но непонятной — в первой легко найти ошибку и поправить, а во вторую сложно вносить изменения. Поэтому существуют стили кодирования — некие соглашения между программистами, если не следовать которым, можно быть непонятым. Например, если написать:

    все подумают, что Ъ будет напечатан 10 раз, а на самом деле — 1. Есть официальный стайлгайд от Sun. Обязательные к исполнению правила (данный список может меняться, следите за обновлениями):

    • Программа должна собираться без предупреждений компилятора.
    • Вложенные операторы должны выделяться отступом, операторы одного уровня вложенности должны быть на одном уровне отступов. Отступы должны быть 4 пробела или 1 табуляция (но что-то одно во всей программе!). Используйте пустые строки, чтобы выделять логически связные куски кода.
    • В описании класса должны идти открытые конструкторы, затем static и public методы, затем public поля (которых быть на самом деле не должно, см. правило 7), затем private конструкторы и методы, затем private поля
    • На одной строке должно быть только одно определение. Неправильно писать
    • Нельзя объявлять переменные, совпадающие по имени с переменными, объявленными в объемлющем блоке (избегайте скрытия переменных).
    • Допустимо, чтобы имена параметров метода и полей совпадали.
    • Не должно быть раскопированного кода. Выделяйте общие куски в отдельные методы.
    • Не должно быть public-полей.
    • Не следует писать несколько операторов на одной строке, например,

    следует писать как

    • По возможности сужайте области видимости переменных, набор допустимых операций и т.д. (например, пишите final везде, где только можно). Тогда если что-то пошло не так, вы сможете узнать об этом уже на этапе компиляции.
    • Не используйте goto. Вообще, старайтесь, чтобы поток выполнения программы был прост и понятен.
    • Одна сущность должна отвечать за одно действие и играть одну роль по всей программе. Один метод должен делать что-то одно, если метод делает что-то и что-то ещё, его надо разбить на два. То же касается классов — у них должна быть чётко очерченная область ответственности. Одну и ту же переменную нельзя использовать в двух различных ролях.
    • Не пишите методов размером больше экрана, разбивайте их на мелкие методы.
    • Выбирайте подходящие имена для переменных, методов и классов. Называйте переменные и методы с маленькой буквы, а свои типы (в т.ч. классы и интерфейсы) с большой. Если в имени переменной или метода содержится несколько слов, то все, кроме первого, должны начинаться с заглавной буквы (без каких-либо символов подчеркивания). Имена переменных (за исключением счетчиков циклов), функций и типов данных не должны быть короче 4 символов.
    • Не используйте "магические константы".
    • Выделяйте пробелами арифметические операции, оператор присваивания и т.д.
    • Не отделяйте пробелами скобки.
    • Ставьте пробел после ключевого слова: между if и (, for и ( и т.д. Например, правильно оформленный for:
    • Предложения case в операторе switch должны оформляться следующим образом:
    • Методы-предикаты (возвращающие булево значение) следует именовать следующим образом:

    где "глагол" — глагол бытия (to be) или обладания (to have) в сооветствующей форме, а "предикат" — проверяемое свойство. Например:

    • При вызове функций-предикатов запрещается сравнивать результат с логическими константами.
    • Не используйте транслит, пишите все либо по-русски в читабельной в компьютерном классе кодировке, либо по-английски. Например, vstavka() — неудачное название для функции, реализующей алгоритм сортировки вставками.
    • Если вы выделяете системные ресурсы (файловые дескрипторы, etc), то вы обязательно должны их освободить, как только в них отпадает нужда.
    • Каждый вывод данных на экран должен сопровождаться сообщением с пояснением того, что именно выводится. Вообще, пользовательский интерфейс должен быть понятен человеку, ни разу не видевшему программу
    • Каждый ввод пользовательских данных должен сопровождаться приглашением к вводу, объясняющим пользователю, ввод данных какого рода и в каком объеме от него ожидается.

    [an error occurred while processing the directive]
    Карта сайта