Merge pull request #7499 from electron/clang-format

Add a guide to use clang-format

.clang-format

@@ -0,0 +1,35 @@
+# Defines the Chromium style for automatic reformatting.
+# http://clang.llvm.org/docs/ClangFormatStyleOptions.html
+BasedOnStyle: Chromium
+# This defaults to 'Auto'. Explicitly set it for a while, so that
+# 'vector<vector<int> >' in existing files gets formatted to
+# 'vector<vector<int>>'. ('Auto' means that clang-format will only use
+# 'int>>' if the file already contains at least one such instance.)
+Standard: Cpp11
+# Make sure code like:
+# IPC_BEGIN_MESSAGE_MAP()
+#   IPC_MESSAGE_HANDLER(WidgetHostViewHost_Update, OnUpdate)
+# IPC_END_MESSAGE_MAP()
+# gets correctly indented.
+MacroBlockBegin: "^\
+BEGIN_MSG_MAP|\
+BEGIN_MSG_MAP_EX|\
+BEGIN_SAFE_MSG_MAP_EX|\
+CR_BEGIN_MSG_MAP_EX|\
+IPC_BEGIN_MESSAGE_MAP|\
+IPC_BEGIN_MESSAGE_MAP_WITH_PARAM|\
+IPC_PROTOBUF_MESSAGE_TRAITS_BEGIN|\
+IPC_STRUCT_BEGIN|\
+IPC_STRUCT_BEGIN_WITH_PARENT|\
+IPC_STRUCT_TRAITS_BEGIN|\
+POLPARAMS_BEGIN|\
+PPAPI_BEGIN_MESSAGE_MAP$"
+MacroBlockEnd: "^\
+CR_END_MSG_MAP|\
+END_MSG_MAP|\
+IPC_END_MESSAGE_MAP|\
+IPC_PROTOBUF_MESSAGE_TRAITS_END|\
+IPC_STRUCT_END|\
+IPC_STRUCT_TRAITS_END|\
+POLPARAMS_END|\
+PPAPI_END_MESSAGE_MAP$"

docs/README.md

@@ -89,6 +89,7 @@ an issue:
 ## Development
 
 * [Coding Style](development/coding-style.md)
+* [Using clang-format on C++ Code](development/clang-format.md)
 * [Source Code Directory Structure](development/source-code-directory-structure.md)
 * [Technical Differences to NW.js (formerly node-webkit)](development/atom-shell-vs-node-webkit.md)
 * [Build System Overview](development/build-system-overview.md)

docs/development/clang-format.md

@@ -0,0 +1,34 @@
+# Using clang-format on C++ Code
+
+[`clang-format`](http://clang.llvm.org/docs/ClangFormat.html) is a tool to
+automatically format C/C++/Objective-C code, so that developers don't need to
+worry about style issues during code reviews.
+
+It is highly recommended to format your changed C++ code before opening pull
+requests, which will save you and the reviewers' time.
+
+You can install `clang-format` and `git-clang-format` via
+`npm install -g clang-format`.
+
+To automatically format a file according to Electron C++ code style, simply run
+`clang-format -i path/to/electron/file.cc`. It should work on macOS/Linux/Windows.
+
+The workflow to format your changed code:
+
+1. Make codes changes in Electron repository.
+2. Run `git add your_changed_file.cc`.
+3. Run `git-clang-format`, and you will probably see modifications in
+  `your_changed_file.cc`, these modifications are generated from `clang-format`.
+4. Run `git add your_changed_file.cc`, and commit your change.
+5. Now the branch is ready to be opened as a pull request.
+
+If you want to format the changed code on your latest git commit (HEAD), you can
+run `git-clang-format HEAD~1`. See `git-clang-format -h` for more details.
+
+## Editor Integration
+
+You can also integrate `clang-format` directly into your favorite editors.
+For further guidance on setting up editor integration, see these pages:
+
+  * [Atom](https://atom.io/packages/clang-format)
+  * [Vim & Emacs](http://clang.llvm.org/docs/ClangFormat.html#vim-integration)

docs/development/coding-style.md

@@ -8,8 +8,9 @@ You can run `npm run lint` to show any style issues detected by `cpplint` and
 ## C++ and Python
 
 For C++ and Python, we follow Chromium's [Coding
-Style](http://www.chromium.org/developers/coding-style). There is also a
-script `script/cpplint.py` to check whether all files conform.
+Style](http://www.chromium.org/developers/coding-style). You can use
+[clang-format](clang-format.md) to format the C++ code automatically. There is
+also a script `script/cpplint.py` to check whether all files conform.
 
 The Python version we are using now is Python 2.7.