From 4a74548c225ecada66b286a55c3c8fa0f2eea635 Mon Sep 17 00:00:00 2001 From: Dave Borowitz Date: Tue, 7 Feb 2017 09:22:33 -0500 Subject: [PATCH] Document gjf and add a script to standardize/streamline setup google-java-format is not uniformly available in package management systems across OSes. More importantly, we want to make sure that all contributors are using a standardized version, to avoid unnecessary changes due to slight differences between versions. While we're in the dev documentation, link to the Google Java Style Guide, and remove some wording that is clearly redundant with the style guide. Change-Id: Ib14dab2e692339f836083fad08a7a435a2f24470 --- .gitignore | 1 + Documentation/dev-contributing.txt | 39 ++--- tools/GoogleFormat.xml | 267 ----------------------------- tools/download_file.py | 2 +- tools/setup_gjf.sh | 66 +++++++ 5 files changed, 86 insertions(+), 289 deletions(-) delete mode 100644 tools/GoogleFormat.xml create mode 100755 tools/setup_gjf.sh diff --git a/.gitignore b/.gitignore index 023be05d31..7893b60fab 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,4 @@ /infer-out /local.properties /test_site +/tools/format diff --git a/Documentation/dev-contributing.txt b/Documentation/dev-contributing.txt index 8d16ca1915..0cd545406d 100644 --- a/Documentation/dev-contributing.txt +++ b/Documentation/dev-contributing.txt @@ -147,27 +147,26 @@ Password tab of the user settings page]. === Style -The basic coding style is covered by the tools/GoogleFormat.xml -doc, see the link:dev-eclipse.html#Formatting[Eclipse Setup] -for that. +Gerrit generally follows the +link:https://google.github.io/styleguide/javaguide.html[Google Java Style +Guide]. -Highlighted/additional styling notes: +To format source code, Gerrit uses the +link:https://github.com/google/google-java-format[`google-java-format`] +tool (version 1.2), which automatically formats code to follow the +style guide. Using this tool streamlines code review by reducing the +need for time-consuming, tedious, and contentious discussions about +trivial issues like whitespace. - * It is generally more important to match the style of the nearby - code which you are modifying than it is to match the style - in the formatting guidelines. This is especially true within the - same file. - * Review your change in Gerrit to see if it highlights - mistakenly deleted/added spaces on lines, trailing spaces. - * Line length should be 80 or less, unless the code reads - better with something slightly longer. Shorter lines not only - help reviewers who may use a tablet to review the code, but future - contributors may also like to open several editors side by - side while editing new changes. - * Use 2 spaces for indent (no tabs) - * Use braces in all if/else/for/do/while/catch blocks, spaces before/after - if/for/while/catch parens. - * Use /** */ style Javadocs for variables. +You may download and run `google-java-format` on your own, or you may +run `./tools/setup_gjf.sh` to download a local copy and set up a +wrapper script. If you run your own copy, please use the same version, +as there may be slight differences between versions. + +When considering the style beyond just formatting rules, it is often +more important to match the style of the nearby code which you are +modifying than it is to match the style guide exactly. This is +especially true within the same file. Additionally, you will notice that most of the newline spacing is fairly consistent throughout the code in Gerrit, it helps to @@ -176,8 +175,6 @@ examples: * Keep a blank line between all class and method declarations. * Do not add blank lines at the beginning or end of class/methods. - * Put a blank line between external import sources, but not - between internal ones. When to use `final` modifier and when not (in new code): diff --git a/tools/GoogleFormat.xml b/tools/GoogleFormat.xml deleted file mode 100644 index 2c65b16ee7..0000000000 --- a/tools/GoogleFormat.xml +++ /dev/null @@ -1,267 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/tools/download_file.py b/tools/download_file.py index 8f5aa7c4f2..38c2974a7d 100755 --- a/tools/download_file.py +++ b/tools/download_file.py @@ -104,7 +104,7 @@ if not path.exists(cache_ent): print('Download %s' % src_url, file=stderr) try: - check_call(['curl', '--proxy-anyauth', '-ksSfo', cache_ent, src_url]) + check_call(['curl', '--proxy-anyauth', '-ksSfLo', cache_ent, src_url]) except OSError as err: print('could not invoke curl: %s\nis curl installed?' % err, file=stderr) exit(1) diff --git a/tools/setup_gjf.sh b/tools/setup_gjf.sh new file mode 100755 index 0000000000..6b03640154 --- /dev/null +++ b/tools/setup_gjf.sh @@ -0,0 +1,66 @@ +#!/bin/bash +# +# Copyright (C) 2017 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. + +set -eu + +# Keep this version in sync with dev-contributing.txt. +VERSION="1.2" +SHA1="b3614824e178dd918dc2cc7c7b54804200ebfc64" + +root="$(git rev-parse --show-toplevel)" +if [[ -z "$root" ]]; then + echo "google-java-format setup requires a git working tree" + exit 1 +fi + +dir="$root/tools/format" +mkdir -p "$dir" + +name="google-java-format-$VERSION-all-deps.jar" +url="https://github.com/google/google-java-format/releases/download/google-java-format-$VERSION/$name" +"$root/tools/download_file.py" -o "$dir/$name" -u "$url" -v "$SHA1" + +launcher="$dir/google-java-format" +cat > "$launcher" <