Updating android Development Specification

Abstract

• preface
• AS the specification
• Naming conventions
• Resource file specification
• Unified version specification
• Third-party library specification
• Annotation specifications
• Test specification
• RN specification
• Some other specifications

preface

In order to facilitate the maintenance of the project and the development of the specification, and to promote the efficiency of Code Review among members, the following development specification is proposed. If you have better suggestions, please go to GitHub to propose an issue.

AS the specification

To do a good job, he must sharpen his tools.

1. Develop with the latest version of the IDE whenever possible;
2. The encoding format is UTF-8.
3. After editing. Java and. XML files, be sure to format them (indent alignment is consistent with the default AS).
4. Delete unnecessary imports to reduce warningsOptimize ImportsShortcuts;
5. AS common development plug-ins can be referred to here ~ AS common development plug-ins

Naming conventions

1. The package name

Package names are all lowercase, and consecutive words are simply concatenated without underscores.

Use the anti – domain name naming rules, use all lowercase letters. The level-1 package name is a top-level domain name, usually com, edu, gov, net, org, etc. The level-2 package name is the company name, the level-2 package name is based on the application, and the level-4 package name is the module name or layer name.

Note: If the project adopts MVP, all interfaces extracted from M, V, and P are placed under the I package of the corresponding module, and all implementations are placed under the IMPL of the corresponding module

2. The name of the class

Class names are written in UpperCamelCase style.

A class name is usually a noun or noun phrase, and an interface name may sometimes be an adjective or adjective phrase. There is no specific rule or well-established convention for naming annotation types.

For nouns, use the big hump nomenclature. Avoid abbreviations unless the abbreviations are well-known, such as HTML or URL. If the class name contains abbreviations, capitalize each letter of the abbreviations.

The name of a Test class starts with the name of the class it is testing and ends with Test. For example, HashTest or HashIntegrationTest.

Interface: The same naming rules as classes use the big camel name, and most end with able or ible, such as interface Runnable and interface Accessible.

Note: If the project uses MVP, all Model, View, and Presenter interfaces are prefixed with I without suffix, and all other interfaces are named in the same way.

3. The method name

Method names are written in lowerCamelCase style.

Method names are usually verbs or phrasal verbs.

4. Constant names

Constant names are named in CONSTANT_CASE, all uppercase letters, and words are separated by underscores. So, what exactly is a constant?

Each constant is a static final field, but not all static final fields are constants. When deciding whether a field is a constant, consider whether it really feels like one. For example, if the observed state of any of the instances is variable, it will almost certainly not be a constant. It’s generally not enough that you never intend to change an object, it has to really stay the same to show it as a constant.

// Constants
static final int NUMBER = 5;
static final ImmutableListNAMES = ImmutableList.of("Ed"."Ann");
static final Joiner COMMA_JOINER = Joiner.on(', '); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }
// Not constants
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final SetmutableCollection = new HashSet();
static final ImmutableSetmutableElements = ImmutableSet.of(mutable);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these"."can"."change"};Copy the code

5. Name of the variable field

Variable field names are modified to the following style based on lowerCamelCase style: The basic structure is scopeVariableNameType.

Scope: the scope of

Non-public, non-static field names start with m.

Static field names start with s.

Public non-static field names start with P.

Public static field (global variable) names start with G.

Example:

public class MyClass {
      int mPackagePrivate;  
      private int mPrivate;  
      protected int mProtected;
      private static MyClass sSingleton;  
      public int pField;
      public static int gField;
}Copy the code

Use a one-character prefix to indicate the scope. The one-character prefix must be lowercase, followed by a name composed of one or more ideographic words. In addition, the first letter of each word is capitalized and the other letters are lowercase, which ensures that the variable name can be correctly delimited.

Type: Type

Considering the use of many UI controls in Android, in order to avoid confusion between controls and ordinary member variables and better meaning, all member variables used to represent controls are unified with control abbreviations as suffixes (with a list of abbreviations at the end of the article).

Generally, type suffixes are not added to common variables. If type suffixes are added uniformly, please refer to the abbreviation table at the end of this article.

By placing a quantifier at the end, you create more uniform variables that are easier to understand and search for.

Note: If ButterKnife is used in your project, do not add the m prefix and name it in the lowerCamelCase style.

For example, use mCustomerStrFirst and mCustomerStrLast instead of mFirstCustomerStr and mLastCustomerStr.

Description:

Set add the following suffix: List, Map, Set Array add the following suffix: Arr

Note: All VO (value objects) are written in the standard lowerCamelCase style, and all Dtos (data transfer objects) are written according to the field names defined in the interface documentation.

6. The parameter name

Parameter names are written in lowerCamelCase style. Parameters should avoid single character names.

7. Local variable names

Local variable names are written in lowerCamelCase style and can have looser abbreviations than other types of names.

Although abbreviations are looser, avoid single-character names, except for temporary and circular variables.

Even if a local variable is final and immutable, it should not be shown as a constant, nor should it be named as a constant.

8. Temporary variables

Temporary variables, usually named I, j, k, m, and n, are used for integers; C, D, e, these are commonly used for character types. For (int I = 0; i < len ; I++).

9. Type variable name

Type variables can be named in one of two styles:

A single uppercase letter followed by a number (E, T, X, T2).

Use the class name (see 2. Class name) followed by a capital T(e.g. RequestT, FooBarT).

More also can refer to alibaba Java development manual

Resource file specification

1. Resource Layout file (XML file)

All lowercase, using the underscore naming method

1) the contentview

All words must be in lower case, underlined between words, using nouns or noun groups.

The contentView of any Activity or Fragment must correspond to its class name as follows:

Convert all letters to lowercase and switch types and functions (suffixes to prefixes).

For example: activity_main. XML

2) Dialog name:Dialog_ description. XML

For example: dialog_hint. XML

3) PopupWindow name:Ppw_ description. XML

For example: ppw_info. XML

4) List item naming:Item_ description. XML

For example: item_city. XML

5) Include item name:Module _(location) description.xml

For example, activity_main_head. XML and activity_main_bottom.xml

Note: The common include item names are: project name abbreviation _ description.xml

For example: xxxx_title. XML

2. Resource file (image drawable folder)

All lowercase, use the underscore naming method, prefix to distinguish

Naming mode: _small indicates a small image, _BIG indicates a large image, and the logical name can consist of multiple words and underscores. The following rules apply:

Usage _ Module name _ Logical Name Usage _ Module name _ Color Usage _ Logical name Usage _ Color

Description: Usage also charges piece type (see UI control abbreviation table for details)

Such as:

Btn_main_home. PNG buttons

Divider_maket_white. PNG divider

Ic_edit. PNG icon

Bg_main. PNG background

Btn_red. PNG Red button

Btn_red_big. PNG Big red button

Ic_head_small. PNG small head

PNG Background of the input box

Divider_white.png White dividing line

If you have multiple forms except for buttons like btn_xx.xml (selector)

Note: using the plugin SelectorChapek from AndroidStudio you can quickly generate selectors, as long as you name them properly.

3. Animation file (under anim folder)

All lowercase, use the underscore naming method, prefix to distinguish.

The following rules are used for specific animations:

Module name _ Logical name

Logical name

refresh_progress.xml

market_cart_add.xml

market_cart_remove.xml

A normal Tween animation is named in the following table

// Start with the type of animation and end with the direction

4. Set values to name

1) colors.xml

The name of colors is named using the underscore naming method. In your colors.xml file, it should be just the name of the mapped color, an ARGB value, and nothing else. Do not use it to define ARGB values for different buttons.

Don’t do that

  <resources>
      <color name="button_foreground">#FFFFFF</color>
      <color name="button_background">#2A91BD</color>
      <color name="comment_background_inactive">#5F5F5F</color>
      <color name="comment_background_active"># 939393</color>
      <color name="comment_foreground">#FFFFFF</color>
      <color name="comment_foreground_important">#FF9D2F</color>.<color name="comment_shadow"># 323232</color>Copy the code

With this format, it is very easy to start redefining RGBA values, which makes it very complicated to change the base color if needed. Also, these definitions are associated with some environment, such as button or comment, and should be placed in a button style, not in a color.xml file.

Instead, do this:

  <resources>

      <! -- grayscale -->
      <color name="white"     >#FFFFFF</color>
      <color name="gray_light">#DBDBDB</color>
      <color name="gray"      ># 939393</color>
      <color name="gray_dark" >#5F5F5F</color>
      <color name="black"     ># 323232</color>

      <! -- basic colors -->
      <color name="green">#27D34D</color>
      <color name="blue">#2A91BD</color>
      <color name="orange">#FF9D2F</color>
      <color name="red">#FF432F</color>

  </resources>Copy the code

Ask the app designer for this palette. It doesn’t have to be named “green”, “blue”, etc. Names like “brand_primary”, “brand_secondary”, “brand_negative” are also perfectly acceptable. Standard colors like this are easy to modify or refactor, making it very clear how many different colors are used in the application. It is often important to reduce the number of colors used for a UI with aesthetic value.

2) dimens.xml

Treat dimens. XML like colors.xml and define a color palette, you should also define a “palette” of spacing and font sizes. A good example would look like this:

<resources>

    <! -- font sizes -->
    <dimen name="font_larger">22sp</dimen>
    <dimen name="font_large">18sp</dimen>
    <dimen name="font_normal">15sp</dimen>
    <dimen name="font_small">12sp</dimen>

    <! -- typical spacing between two views -->
    <dimen name="spacing_huge">40dp</dimen>
    <dimen name="spacing_large">24dp</dimen>
    <dimen name="spacing_normal">14dp</dimen>
    <dimen name="spacing_small">10dp</dimen>
    <dimen name="spacing_tiny">4dp</dimen>

    <! -- typical sizes of views -->
    <dimen name="button_height_tall">60dp</dimen>
    <dimen name="button_height_normal">40dp</dimen>
    <dimen name="button_height_short">32dp</dimen>

</resources>Copy the code

When writing margins and Paddings, you should use the spacing_xxxx size format to create layouts instead of writing values as you would for strings. Writing this way is very tactile and makes it very easy to organize and change style or layout.

3) strings.xml

The name of strings uses the underscore naming method and follows the following rules: module name + logical name

Such as:

Main_menu_about Main menu key Text friend_title Friend module title bar friend_dialog_del Friend deletion prompt login_check_email Login verification dialog_title Dialog box title Button_ok confirms that the key loaded the text

4) styles.xml

Almost every project needs to use a style file properly, because it is common for a view to have a duplicate look and feel. Put all the look and feel details (colors, padding, font) in the style file. For most text content in your app, you should at least have a common style file, for example:

<style name="ContentText">
    <item name="android:textSize">@dimen/font_normal</item>
    <item name="android:textColor">@color/basic_black</item>
</style>Copy the code

Apply to TextView:

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/price"
    style="@style/ContentText"
    />Copy the code

You might want to do the same for button controls, don’t stop there. Put a set of related and repeating Android :**** attributes into a common style.

To split a large style file into multiple files, you can have multiple styles.xml files. The Android SDK supports other files, styles the file name does not have any effect, instead it uses the XML

5. Name the ID in layout

The naming mode is: View abbreviations _ module names _ logical names such as Btn_main_search use the AndroidStudio plugin ButterKnife Zelezny, which is handy for generating annotations, or you can use the Android Code Generator plugin.

If you want to subcontract resource files, you can refer to my article ~ Android Studio subcontract resources

Unified version specification

There are many different versions of Android development such as compileSdkVersion, minSdkVersion, targetSdkVersion and dependencies on third-party libraries in your projects. Different modules and developers can have different versions of these. So you need a uniform version of the specification file.

For details, please refer to this blog post I wrote ~ Unified Specification for Android Development

Third-party library specification

Let’s get out of the way and use the latest and hottest technology, amway’s popular Framework Checker, along with your own code that Android developers have to collect

It is hoped that the team can use the current relatively new technology. It is not recommended to build wheels by themselves or use wheels that have stopped maintenance, otherwise the issue cannot be raised if there is a problem.

Personal recommendations team use the Retrofit, RxAndroid OkHttp, Glide/Fresco, Gson/Fastjson, EventBus/AndroidEventBus GreenDao, (Dagger2, Tinker).

Annotation specifications

To make your code easy for others to read, make comments in key areas.

1. The class notes

Each class should be responsible for its own code, annotated with the author’s name and contact information.

/** * 
 * author: Blankj * E-mail: xxx@xx * time: 2017/03/07 * desc: XXXX Description * Version: 1.0 * 
 */Copy the code 
For details, enter Setting → Editor → File and Code Templates → Includes → File Header in AS
** * 
 * Author: ${USER} * E-mail: xxx@xx * time: ${YEAR}/${MONTH}/${DAY} * desc: 1.0 * < / pre > * /


public class WelcomeActivity {... }Copy the code 
This will automatically add the annotation every time you create a new class.
2. Method comments
Every member method (including custom member methods, override methods, and attribute methods) must have a method header comment. Type /** press enter in the first line of the method, and AS will generate the template for you.
/** * bitmap to byteArr **@paramBitmap Bitmap object *@paramThe format format *@returnByte array */
public static byte[] bitmap2Bytes(Bitmap bitmap, CompressFormat format) {
    if (bitmap == null) return null;
    ByteArrayOutputStream baos = new ByteArrayOutputStream();
    bitmap.compress(format, 100, baos);
    return baos.toByteArray();
}Copy the code
3. The piece of annotation
Block comments are indent at the same level as the surrounding code. They can be /*… */ style, also can be //… Style (// preferably followed by a space). For multiple lines /*… */ comment, subsequent lines must start with * and align with the * on the previous line. The following sample comments are OK.
/* * This is // And so /* Or you can * okay. // is this. * even do this. */* /Copy the code
Comments should not be enclosed in frames drawn by asterisks or other characters.

Tip: When writing multi-line comments, if you want to rewrap them if necessary, use /*… * /.

Test specification
After the completion of business development, developers do unit tests. After the completion of unit tests, ensure that all unit tests pass and the unit test code coverage reaches a certain level (this requires development and testing conventions, and the higher the better in theory), and develop and test.
// TODO…
RN specification
// TODO…
Some other specifications

Reasonable layout, effective use<merge>.<ViewStub>.<include>The label
Try to keep related methods together
Don’t forget to detect memory leaks

The appendix
Table 1 UI control abbreviations



View
abbreviations




TextView
txt


EditText
edit


Button
btn


ImageButton
ibtn


ImageView
img


ListView
lv


RadioGroup
rgroup


RadioButton
rbtn


ProgressBar
rbar


SeekBar
seek


CheckBox
cb


Spinner
spinner


TableLayout
table


TableRow
row


LinearLayout
ll


RelativeLayout
rl


ScrollView
scroll


SearchView
search


TabHost
thost


TabWidget
twidget



Table 2 Abbreviations of common English words:



The name of the
abbreviations




icon
IC (mainly used in app ICONS)


color
Cl (mainly for color values)


divider
Di (mainly used to divide lines, including not only dividers in the Listview but also lines in the regular layout)


selector
Sl (mainly used for multiple states of a view, including not only the selector in the Listview, but also the selector of the button)


average
avg


background
Bg (mainly used as background for layouts and sub-layouts)


buffer
buf


control
ctrl


delete
del


document
doc


error
err


escape
esc


increment
inc


infomation
info


initial
init


image
img


Internationalization
I18N


length
len


library
lib


message
msg


password
pwd


position
pos


server
srv


string
str


temp
tmp


window
wnd(win)



Rule of abbreviations in programs: Do not use abbreviations unless the abbreviations are conventional.
reference
Android development best practices
Android Coding Specification
Alibaba Java Development Manual
Google Java Programming Style Guide
Version of the log

17/03/06: version1.0, powered by Blankj(tsai)