HACKING

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.