Рекомендации к стилю кода
Существуют соглашения, по поводу использования Java библиотек и инструментов для Android. В некоторых случаях соглашения могут быть изменены, например, в таких как использование старого кода, который, возможно, использует неодобренный паттерн или библиотеку.
Правила Java стиля
Программы гораздо проще поддерживать, когда все файлы имеют согласованный стиль. Мы следуем стандартному стилю программирования на Java, определенному Sun в их Code Conventions for the Java Programming Language, с несколькими исключениями и дополнениями. Данное руководство по стилю является подробным и всесторонним, а также широко используется Java сообществом.
- Комментарии/Javadoc: пишите их; используйте стандартный стиль.
- Короткие методы: не пишите гигантских методов.
- Поля: должны быть вверху файла, или прямо перед методом, который их использует.
- Локальные переменные: ограничивайте область видимости.
- Импорты: android; сторонние (в алфавитном порядке); java(x)
- Отступы: 4 пробела, без табуляций.
- Длина строки: 100 символов.
- Имена полей: не public и не static поля начинаются с «m».
- Фигурные скобки: открывающие фигурные скобки не находятся в отдельной строке.
- Аннотации: используйте стандартные аннотации.
- Сокращения: используйте сокращения как слова в именах, например, XmlHttpRequest, getUrl() и т.п.
- Стиль TODO: «TODO: пишите описание здесь».
- Согласованность: смотрите, что находится вокруг вас.
Правила языка Java
Не игнорируйте исключения
void setServerPort(String value) < try < serverPort = Integer.parseInt(value); >catch (NumberFormatException e) < >> void setServerPort(String value) throws NumberFormatException
void setServerPort(String value) throws ConfigurationException < try < serverPort = Integer.parseInt(value); >catch (NumberFormatException e) < throw new ConfigurationException("Port " + value + " is not valid."); >> /** Set port. If value is not a valid number, 80 is substituted. */ void setServerPort(String value) < try < serverPort = Integer.parseInt(value); >catch (NumberFormatException e) < serverPort = 80; // default port for server >> /** Set port. If value is not a valid number, die. */ void setServerPort(String value) < try < serverPort = Integer.parseInt(value); >catch (NumberFormatException e) < throw new RuntimeException("port " + value " is invalid, ", e); >> /** If value is not a valid number, original port number is used. */ void setServerPort(String value) < try < serverPort = Integer.parseInt(value); >catch (NumberFormatException e) < // Method is documented to just ignore invalid user input. // serverPort will just be unchanged. >> Не перехватывайте обобщенные исключения
Вам не следует так делать. Суть в том, что возможно появление исключения, которого вы не ожидали и, в итоге, ошибка будет отлавливаться на уровне приложения. То есть, если кто-то добавит новый тип исключения, то компилятор не сможет вам помочь понять, что это другая ошибка.
Существуют редкие исключения из этого правила: определенный тестовый код, или код верхнего уровня, где вы хотите перехватывать все типы ошибок (для того, чтобы предотвратить их отображение в пользовательском интерфейсе, или чтобы продолжить какую-то пакетную задачу).
- Перехватывайте каждое исключение отдельно в блоке catch, после одиночного try. Возможно это неудобно, но всё равно это предпочтительный способ для перехвата всех исключений.
- Измените ваш код для более гранулированной обработки ошибок с несколькими блоками try. Отделите IO от парсинга, обрабатывайте ошибки отдельно в каждом случае.
- Перебросьте исключение. Во многих случаях вам не нужно обрабатывать все исключения на текущем уровне, просто позвольте методу перебросить их.
Финализаторы
Что это: Финализаторы — это способ запускать программный код перед тем как объект собирается сборщиком мусора.
За: могут быть полезны при очистке, в особенности внешних ресурсов.
Против: нет никаких гарантий того, когда будет вызван финализатор, и, вообще, будет ли он вызван.
Решение: Мы не используем финализаторы. В большинстве случаев, всё то, что вам нужно от финализатора, вы сможете сделать при помощи обработки исключений. Если вам действительно нужен финализатор, то объявите метод close() и задокументируйте, когда он точно будет вызываться.
Импорты
Групповой символ в импортах
Решение: Используйте стиль #2 для импорта любого Android кода. Явное исключение делается для стандартных библиотек (java.util.*, java.io.*, и т.п) и для кода модульного тестирования (junit.framework.*).
Комментарии/Javadoc
Каждый файл должен иметь объявление об авторских правах в самом начале. Далее идут объявления операторов package и import, причем каждый блок разделяется пустой строкой. За ними следуют объявления класса или интерфейса. Опишите, что делает класс в Javadoc-комментариях.
/* * Copyright (C) 2010 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.android.internal.foo; import android.os.Blah; import android.view.Yada; import java.sql.ResultSet; import java.sql.SQLException; /** * Does X and Y and provides an abstraction for Z. */ public class Foo
Каждый класс и нетривиальный public метод должен содержать Javadoc, по крайней мере с одной фразой, описывающей что он делает. Фраза должна начинаться с описательного глагола 3-го лица. Примеры:
/** Returns the correctly rounded positive square root of a double value. */ static double sqrt(double a) < >/** * Constructs a new String by converting the specified array of * bytes using the platform's default character encoding. */ public String(byte[] bytes)
Вам не нужно описывать Javadoc для тривиальных get и set методов, таких как setFoo(), если ваш Javadoc говорит только «sets Foo». Если метод делает что-то более сложное (например, соблюдение неких ограничений, или если его действия имеют важный эффект вне его самого), тогда его обязательно нужно задокументировать. И если это не просто объяснение того, что означает Foo, то вам также следует его задокументировать.
Вообще, любой метод, который вы написали получает пользу от Javadoc, неважно public он или нет. Public методы являются частью API, и поэтому они требуют описания в Javadoc.
Для написания Javadoc’ов вам следует придерживаться Sun Javadoc conventions.
Короткие методы
Методы должны быть небольшими и решающими конкретную задачу настолько, насколько это возможно. Однако, понятно, что иногда большие методы бывают целесообразны, так что нет строгого ограничения на длину метода. Если метод превышает 40 строк, то вам, возможно, стоит подумать о том, можно ли его разбить на части, не нарушив структуры программы.
Локальные переменные
Область видимости локальных переменных должна сводиться к минимуму. Делая это, вы улучшаете читаемость и поддерживаемость кода, а также уменьшаете вероятность ошибок. Каждая переменная должна объявляться в самом глубоком блоке, который окружает все возможные места использования переменной.
Локальные переменные должны объявляться в том месте, где впервые необходимо её использовать. Почти каждая локальная переменная нуждается в инициализаторе. Если вы еще не знаете, как точно инициализировать переменную, то вам следует отложить её объявление, пока вы это не узнаете.
Существует одно исключение, касательно блока try-catch. Если переменная инициализируется при помощи оператора return метода, который выбрасывает проверяемое исключение, то она должна инициализироваться в блоке try. Если же переменная должна использоваться вне блока try, тогда она объявляется перед ним, неважно, знаете ли вы как её точно нужно инициализировать:
// Instantiate class cl, which represents some sort of Set Set s = null; try < s = (Set) cl.newInstance(); >catch(IllegalAccessException e) < throw new IllegalArgumentException(cl + " not accessible"); >catch(InstantiationException e) < throw new IllegalArgumentException(cl + " not instantiable"); >// Exercise the set s.addAll(Arrays.asList(args)); Set createSet(Class cl) < // Instantiate class cl, which represents some sort of Set try < return (Set) cl.newInstance(); >catch(IllegalAccessException e) < throw new IllegalArgumentException(cl + " not accessible"); >catch(InstantiationException e) < throw new IllegalArgumentException(cl + " not instantiable"); >> . // Exercise the set Set s = createSet(cl); s.addAll(Arrays.asList(args)); Переменные в циклах должны объявляться внутри самого оператора, если только нет непреодолимой причины этого не делать.
for (int i = 0; i for (Iterator i = c.iterator(); i.hasNext(); )
Импорты
- Android импорты.
- Сторонние импорты (com, junit, net, org).
- java и javax.
- Отсортированы по алфавиту внутри каждой группы.
- Заглавные буквы должны быть впереди букв нижнего регистра (например, Z перед a).
- Главные группы должны разделяться пустой строкой.
- Импорты, которые люди хотят видеть в первую очередь, находятся вверху (android).
- Импорты, которые люди хотят видеть в последнюю очередь, находятся внизу (java).
- Люди могут с легкостью использовать этот стиль.
- IDE может придерживаться этого стиля.
Отступы
мы используем 4 пробела для блоков. Мы никогда не используем табуляцию. Мы используем 8 пробелов для переноса строк, включая вызовы функций и присваивания, например правильно так:
Instrument i = someLongExpression(that, wouldNotFit, on, one, line); Instrument i = someLongExpression(that, wouldNotFit, on, one, line); Названия полей
- Не static и не public имена начинаются c «m».
- static поля начинаются с «s».
- Другие поля начинаются с буквы нижнего регистра.
- Поля public static final (константы) пишутся полностью в верхнем регистре, с использованием подчеркивания (ALL_CAPS_WITH_UNDERSCORES)
Фигурные скобки
Для открывающих фигурные скобок не выделяется отдельная строка, они находятся в той же строке, что и код перед ними:
class MyClass < int func() < if (something) < // . >else if (somethingElse) < // . >else < // . >> > Мы требуем фигурные скобки для оператора условия. Исключением является, когда оператор условия и его тело помещаются в одну строку. То есть можно писать так:
if (condition) < body(); // ok >if (condition) body(); // ok Длина строки
Каждая строка текста в коде должна быть не длиннее 100 символов.
Исключение: если комментарий содержит пример команд, или URL (удобнее использовать copy/paste).
Исключение: строки импорта могут быть длиннее 100 символов, так как люди редко на них смотрят. Также это упрощает написание инструментов.
Сокращения в именах
Рассматривайте сокращения и аббревиатуры как слова. Имена более удобочитаемы:
| Хорошо | Плохо |
| XmlHttpRequest | XMLHTTPRequest |
| getCustomerId | getCustomerID |
Этот стиль также применяется, когда сокращение и аббревиатура — это полное имя:
| Хорошо | Плохо |
| class Html | class HTML |
| String url; | String URL; |
| long id; | long ID; |
Стиль TODO
Используйте комментарии TODO для кода, который является временным, краткосрочным, или хорошим, но не идеальным. Комментарий должен включать в себя «TODO:», например:
// TODO: Remove this code after the UrlTable2 has been checked in. // TODO: Change this to use a flag instead of a constant. Если ваш комментарий имеет вид «В будущем сделать что-то», то убедитесь, что он включает в себя конкретную дату (1 января 2011 года), или конкретное событие «Удалить после выхода версии 2.1».
Согласованность
Если вы изменяете код, то потратьте минуту на то, чтобы посмотреть на код вокруг вас и определить его стиль. Если в нем используются пробелы, то и вам следует их использовать. Если комментарии содержат небольшой набор звездочек, то и вам следует их использовать.
Весь смысл рекомендаций к стилю кода в создании общей лексики, чтобы люди концентрировались на том, что они говорят, вместо того как они говорят. Мы представляем глобальные правила стиля, чтобы люди знали эту лексику. Но локальный стиль также важен. Если код, который вы добавляете в файл выглядит резко отличным от того, что был, то это выбросит будущего читателя из его ритма и будет мешать ему понимать структуру. Старайтесь избегать этого.