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.,

       ::DBus::Variant var;
       int8 data = var.reader().get_byte();

    rather than

       ::DBus::Variant var;
       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.

    ::DBus::Variant var;
    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.

  - Write data via the appropriate named method. E.g.,

       ::DBus::Variant var;
       int16_t data;
       var.writer().append_int16(data);

    rather than

       ::DBus::Variant var;
       int16_t data;
       var.writer() << data;

    RATIONALE: Similarly as for reading, the explicit version is only
    marginally longer, and does not require the reader to understand
    overload resolution.

  - Where there is no named method, write by using the stream
    insertion operator. E.g.

       ::DBus::Variant var;
       ::DBus::MessageIter writer;
       map<string, string> data;
       writer = var.writer();
       writer << data;

    RATIONALE: This case is somewhat unfortunate, because it's not as
    clear as its analogue for reading. However, the alternative is to
    duplicate the code of the stream insertion operator overloads.

    Note that the writer can't be omitted. E.g.

       ::DBus::Variant var;
       map<string, string> data;
       var.writer() << data;

    does not work (at least for some types of |data|). Without the
    intermediate variable, g++ seems to ignore templates during
    overload resolution.

- 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.