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.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..69b4855
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,27 @@
+// Copyright (c) 2011 The Chromium OS Authors. All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+// * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+// * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+// * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.