Code Style Guide

This style guide outlines the coding conventions followed by the Android team at DJI and must be followed by all contributors. We welcome your feedback via issues and pull requests. We use the Android Developers Kotlin Style Guide and Android Open Source Project Java Code Style. Additionally, Kotlin and Java classes must follow the Interoperability Guide. We have a few exceptions, additions and notable points we would like to emphasize as follows:

1. Naming conventions: Ensure your variables and methods are named according to their usage.
   • For variables in a class use camel case. Do not prefix "s", or "m", or underscores to the variables.
   • For public static final fields (constants) use all capital letters with underscores.
   • For class names use Pascal case.
   • For method names use camel case in the code.
   • For test methods use camel case with underscores with the format classBeingTested_functionBeingTested_ExpectedResult.
   • For enum class names use camel case, and for enum values use all capital letters with underscores (same as constants).
   • For resource IDs use underscore case. Eg my_resource_name
   • Use the @JvmName annotation when required for Kotlin properties to ensure the names follow conventions when called from Java code For example:

private const val SOME_CONSTANT = 42
class MyClass {
    val someNumber: Int
    private val privateVariable: Int
    protected val protectedVariable: Int

    enum class MyEnum {
    	MY_ENUM_VALUE_1,
        MY_ENUM_VALUE_2,
    	MY_ENUM_VALUE_3
    }
} 

public class MyClass {
    public static final int SOME_CONSTANT = 42;
    public int someNumber;
    private static MyClass singleton;
    int packagePrivate;
    private int privateVariable;
    protected int protectedVariable;

    public enum MyEnum {
    	MY_ENUM_VALUE_1,
    	MY_ENUM_VALUE_2,
    	MY_ENUM_VALUE_3;
    }
} 

2. Explicit Access Level Modifiers: Ensure all java methods, variables and constants in a class have explicit access level modifiers (public, protected or private). Kotlin methods are public by default, so no explicit access level modifier is needed in this case.
3. Inner classes: Avoid creating inner classes in one file unless they are reasonably small. There is no hard limit for the length of the class and it is left to the developer's discretion.
4. Line width and height: When feasible, keep methods small and focused. We recognize that long methods are sometimes appropriate, so no hard limit is placed on the method length. If a method exceeds about 40 lines, try to break it up into helper methods if possible without harming the structure of the program. The width of every line should not exceed 120 characters.
5. Don't repeat yourself: Follow the DRY principle and do not duplicate code - use helper methods instead.
6. Readability: Favor readability over conciseness. For example: Use if-else conditions instead of ternary operators and use descriptive variable names even if they are longer.
7. Documentation: All public methods and classes must be documented. The only exceptions are overridden methods, where the base method must have the documentation.
   • Use standard JavaDoc or KDoc comments for all public methods and classes.
   • Add additional in-line comments as required.
   • Use {@link} in JavaDoc or [] in KDoc for referencing classes, fields, constructors or method names in your description. Use {@see} for other relevant information.
   • Add //TODO comments for anything that has been left without an implementation or is ambiguous and needs further investigation.
   • Use consistent language and capitalization throughout the entire code base.
8. Formatting: Run auto-formatting after you finish editing a file. (The mac shortcut for Android Studio is Command + Option + L).
9. Annotations: Use java annotations like @Nullable and @NonNull for all non-primary data types used as return types or arguments in methods. Also use annotations like @ColorInt, @ColorRes, @Dimension etc. in both Java and Kotlin as required in your code.
10. Resources: All resources should be defined in the resource files and then used in the code, especially strings. Any strings displayed to the user must be defined in the strings.xml file.