shill: document coding conventions
BUG=chromium-os:18369
TEST=FEATURES="test nostrip noclean" emerge-x86-generic shill (yes, paranoia)
Change-Id: Ia99bd5655449b7541d2e759ceab5b79b46d650da
Reviewed-on: http://gerrit.chromium.org/gerrit/4960
Tested-by: mukesh agrawal <quiche@chromium.org>
Reviewed-by: Darin Petkov <petkov@chromium.org>
diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..3a1f7c2
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,62 @@
+Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
+Use of this source code is governed by a BSD-style license that can be
+found in the LICENSE file.
+
+To keep the shill source code consistent, please follow the conventions below:
+
+- Use the Chromium Coding Style, as described at
+ http://www.chromium.org/developers/coding-style.
+
+ If you use Emacs, the Google C Style mode will help you with the formatting
+ aspects of style. (Chromium Style generally follows Google Style). Get the
+ Emacs mode at
+ http://google-styleguide.googlecode.com/svn/trunk/google-c-style.el
+
+ Note that we've deviated from the Chromium style in the following
+ ways. In these cases, follow the shill style, for consistency with
+ the rest of the shill code:
+
+ - We denote pointer and reference variables by placing the '*' and '&'
+ adjacent to the variable name, rather than the type. E.g.
+
+ void *bar
+
+ rather than
+
+ void* bar
+
+ - <no other deviations documented yet>
+
+- When working with DBus::Variant:
+ - Read data via the appropriate named method, rather than depending on
+ implicit conversion. E.g.,
+
+ int8 data = var.reader().get_byte();
+
+ rather than
+
+ int8 data = var;
+
+ RATIONALE: The explicit version is only marginally longer than the
+ implicit version, and does not require the reader to understand C++
+ conversion rules.
+
+ - Where there is no named method, call the appropriate cast operator
+ explicitly. E.g.
+
+ vector<unsigned int> data = var.operator vector<unsigned int>();
+
+ RATIONALE: Calling the cast operator explicitly avoids conflicts with
+ constructors that might also be used to make the conversion. It also
+ avoids requiring that the reader understand C++ conversion rules.
+
+- When deferring work from a signal handler (e.g. a D-Bus callback) to
+ the event loop, name the deferred work function by adding "Task" to
+ the name of the function deferring the work. E.g.
+
+ void Modem::Init() {
+ dispatcher_->PostTask(task_factory_.NewRunnableMethod(&Modem::InitTask));
+ }
+
+ RATIONALE: The naming convention makes the relationship between the signal
+ handler and the task function obvious, at-a-glance.