diff --git a/docs/style_guide.md b/docs/style_guide.md index f61590f9f..b211469c4 100644 --- a/docs/style_guide.md +++ b/docs/style_guide.md @@ -1,4 +1,4 @@ -# Style Guide +# C++ Style Guide The style guide can be summed up as 'clang-format with the Google style set'. In addition, the [Google Style Guide](https://google.github.io/styleguide/cppguide.html) @@ -40,7 +40,7 @@ The buildbot runs `xb lint --all` on the master branch, and will run `xb lint --origin` on pull requests. Run `xb format` before you commit each local change so that you are consistently clean, otherwise you may have to rebase. If you forget, run `xb format --origin` and rebase your changes (so you -don't end up with 5 changes and then a 6th 'whoops' one - that's nasty). +don't end up with 5 changes and then a 6th 'whoops' one — that's nasty). The buildbot is running LLVM 3.8.0. If you are noticing style differences between your local lint/format and the buildbot, ensure you are running that @@ -82,3 +82,44 @@ tabs or linefeeds or whatever again. TODO(benvanik): write a cool script to do this/editor plugins. In the future, the linter will run as a git commit hook and on travis. + +# Android Style Guide + +Android Java and Groovy code and XML files currently don't have automatic format +verification during builds, however, stick to the [AOSP Java Code Style Rules](https://source.android.com/setup/contribute/code-style), +which contain guidelines not only for code formatting, but for the usage of +language features as well. + +The formatting rules used in Xenia match the default Android Studio settings. +They diverge from the C++ code style rules of Xenia in many areas, such as +indentation width and the maximum line length, however, the goal for Android +formatting in Xenia is to ensure quick development environment setup. + +In Java code, limit the length of each line to 100 characters. If an assignment +doesn't fit in the limit, move the right-hand side of it to a separate line with +8-space indentation. Similarly, if the argument list of a method declaration or +a call is too long, start the entire argument list on a new line, also indented +with 8 spaces — this is one of the differences from the C++ code style in Xenia, +where arguments may be aligned with the opening bracket. In general, follow the +[rectangle rule](https://github.com/google/google-java-format/wiki/The-Rectangle-Rule) +so expressions in the code constitute a hierarchy of their bounding rectangles, +ensuring that with 4-space indentation for block contents and 8-space +indentation for subexpressions. + +In XML files, if the width of the line with an element exceeds 100 characters, +or in most cases when there are multiple attributes, each attribute should be +placed on a separate line with 4-space indentation, with the exception of the +first `xmlns`, which should stay on the same line as the element name. + +In Groovy, use 4-space indentation for blocks and 8-space indentation for +splitting arguments into multiple lines. String literals should be written in +single quotes unless string interpolation is used. + +You can use the Code -> Reformat Code and Code -> Reformat File options in +Android Studio to apply coarse formatting rules for different kinds of files +supported by Android Studio, such as Java, XML and Groovy. While clang-format is +very strict and generates code with the single allowed way of formatting, +Android Studio, however, preserves many style choices in the original code, so +it's recommended to approximate the final style manually instead of relying +entirely on automatic formatting. Also use Code -> Rearrange Code to maintain a +consistent structure of Java class declarations.