Wikimedia Apps/Team/Android/Coding conventions

From MediaWiki.org
Jump to navigation Jump to search

Code[edit]

Functional[edit]

  • Classes should avoid public when unnecessary and prefer lesser access modifiers when possible
  • Overridden methods should always use an @Override (phab:T97503) and call the super method if possible
  • Model classes are encouraged to subclass BaseModel
  • Unmarshalling is a responsibility in itself and should not be mixed with a model (except for Gson annotation hints)
  • Catch blocks should be as specific as possible
  • AsyncTasks should be avoided whenever possible; AsyncTasks should be unnecessary for network requests
  • View.post() and View.postDelayed() should be avoided
  • JSON models using @NonNull should use @Required and check for a null response in the data client or initialize to a nonnull value when the service may break contract

Views and Layouts[edit]

  • Butterknife annotations should be used where possible, e.g. @OnClick and others.
  • Views should support both left-to-right and right-to-left locales.
  • The root node of a custom View's XML should be a merge node, with tools:* attributes to aid laying out the view in the AS designer.
  • Buttons should be represented as TextViews with a style of @style/App.Button or any of the color derivatives.

Style[edit]

  • Indentations are 4 spaces
  • Field annotations appear on the same line (needs updating in IDE settings); class and method annotations get their own line (the IDE default)
  • Classes should be slim, modular, of a single responsibility, and unit like; if it's difficult to test a class:
    • Ensure the class exposes its dependencies in the constructor
    • Ensure the class has only one responsibility
  • Member variables do not start with a little "m" (just say mNo to Hungarian Notation)

Terminology[edit]

Naming[edit]
  • All articles are pages but only some pages are articles (e.g., Talk namespace pages are not articles). Use page when referring to either unless the distinction is intended
Abbreviations[edit]
  • WikiSite: wiki
  • Resource identifiers should be name simply id when the method is pointed; ex: @ColorInt getColor(@NonNull Context context, @ColorRes int id)

Tests[edit]

Write tests to improve your development speed, confidence in the submitted implementation, and maintenance costs

  • The person that writes the code, writes the test: new classes that have existing test patterns should be committed with accompanying tests
    • Model classes that have no logic may be excepted
    • View subclasses that are too complex may be excepted but it should be rare that no component of a View could be tested
  • The subject's non-private API should be tested
  • Tests should be short, pointed, and have as few assertions as possible
  • Test classes should be named SubjectTest where Subject is the class under test
  • Test methods should be named testMethodCase where Method is the API under test and Case is the specific configuration scenario
  • All paths should be covered when practical, but tests should always be encouraging.
When do you stop? I'm sure you have heard many times that you cannot prove a program has no bugs by testing. That's true but does not affect the ability of testing to speed up programming. I've seen various proposals for rules to ensure you have tested every combination of everything. It's worth taking a look at these, but don't let them get to you. There is a point of diminishing returns with testing, and there is the danger that by trying to write too many tests, you become discouraged and end up not writing any. You should concentrate on where the risk is. Look at the code and see where it becomes complex. Look at the function and consider the likely areas of error. Your tests will not find every bug, but as you refactor you will understand the program better and thus find more bugs. Although I always start refactoring with a test suite, I invariably add to it as I go along.
—Martin Fowler, Refactoring: Improving the Design of Existing Code

Team norms[edit]

  • If something ought to be done, a patch or Phabricator ticket should be made immediately

Android Studio configuration[edit]

Recommended[edit]

  • Enable warnings for raw types, override annotations, override parameter names

Optional[edit]

  • Disable View -> Navigation bar
  • Disable View -> Toolbar
  • Change the close window keybinding to something more conventional like ctrl + w