root/vidalia/trunk/HACKING

$Id$

              Vidalia Coding and Repository Specification

0. Introduction
  
  This document is intended to loosely specify coding conventions followed in
  Vidalia code, as well as conventions used in Vidalia's Subversion
  repository.

1. Repository Organization

1.1. Subversion Location
  
  Vidalia's repository supports anonymous checkout. You can grab the most
  recent revision of Vidalia's source code via:

    svn co https://svn.vidalia-project.net/svn/vidalia/trunk/ vidalia

1.2 Directory Layout

  The following are the current directories found in Vidalia's SVN repository
  and a general decription of their intended contents:
 
  From https://svn.vidalia-project.net/svn/vidalia:

     ./tags:

        Snapshots of all Vidalia releases will be contained in a sub-directory
        of ./tags, named according to the Vidalia version specification.
        For example, ./tags/vidalia-0.0.1/ would contain the 0.0.1 release of
        Vidalia.
  
     ./trunk:

        Contains the main branch of Vidalia's source code.

     ./trunk/doc:

        Contains Vidalia's documentation, such as specifications and todo
        lists.

     ./trunk/src:

        All Vidalia source code will be contained under this directory.

     ./trunk/src/torcontrol:

        Code in this directory implements Tor's control protocol. It also
        handles things such as starting and stopping Tor and checking the
        status of the Tor process.

     ./trunk/src/vidalia:

       This directory contains code that implements the GUI components of
       Vidalia. Whenever possible and sane, each component should be placed in
       an appropriately-named subdirectory of ./trunk/src/gui.

    ./trunk/src/vidalia/res:

       All GUI-related resource files, such as images, should go in this
       directory. Images should be placed in sub-directories appropriate for
       their image size. For example, 16x16 images would go in
       ./trunk/src/vidalia/res/16x16/
       
    ./trunk/src/common:

       If a source file doesn't belong in the previous directories, it should
       go here. This directory will containg various utility functions, such
       as date or time parsing, custom string manipulation functions, etc. If
       a particular utility has multiple source files, they should all be
       placed in a subdirectory. For example, if there were several source
       files that implemented various string manipulation functions, they
       could go in ./trunk/src/common/string.

2. Coding Conventions
  
  This section aims to provide a small overview of coding conventions used in
  Vidalia, to keep the look of the code consistent between developers and
  contributors. Since it would be impossible to specify all aspects of coding
  here, common sense should be employed for things not specified below.

2.1. Naming Conventions

2.1.1. Source File Names
  
  C++ classes should be divided in to a <classname>.h file, containing the
  class declarations, and a <classname>.cpp file containg the class
  implementation. Each .cpp file should implement only one public class.

  Source files that do not implement a C++ class should be named logically.
  For example, threading code would go in thread.cpp and thread.h.
  
  Filenames should be all lower case to prevent potential cross-platform
  compilation issues due to Windows being case insensitive as opposed to
  nearly every OS being case sensitive.

2.1.2. Class Names

  Class names should begin with a capital letter. If a name is a combination
  of distinct words, each word should be capitalized. The purpose of the class
  should be explained in Doxygen tags. Example:

    /** A brief description of MyClass. */
    /**
     * Alternatively, here is a more detailed description of MyClass.
     */
    class MyClass
    {
    };

2.1.3. Method Names
  
  Method names should begin with a lower case letter. If a method name is a
  combination of distinct words, each word should be capitalized. Methods
  should have descriptions of their purpose in Doxygen tags. Example:

    /** Description of what someMethod does.
     * \param foo The number of foo.
     * \return the return value of someMethod.
     */
    int 
    MyClass::someMethod(int foo)
    {
    }
    
  Note that the method's return type is declared on a line by itself. Private
  member function should NOT have an underscore prepended to their name.

2.1.4. Variable Names

  Variable names should follow a convention similar to method names. Variable
  names should be descriptive if their purpose is non-obvious.

  Variables that are members of a class should have a leading underscore to
  distinguish them from local variables in a method. Member variables should
  also have a description of their purpose in Doxygen tags. For example:

  /** A brief description of MyClass */
  
  /**
   * A more detailed description of MyClass.
   */
  class MyClass
  {
    private:
      int _myVariable; /**< Description of what _myVariable is */
  };
 
2.1.5. Ordering of Method and Member Variable Declarations

  Class member method and variable declarations should be arranged according
  to decreasing order of visibility.

  class MyClass : public QObject
  {
    Q_OBJECT
    
    public:
      /* Public enums */

      /* Public methods */
  
    public slots:
      /* Public slots */

    signals:
      /* Signals emitted by this class */
    
    protected:
      /* Protected methods */

      /* Protected member variables */

    protected slots:
      /* Protected slots */
    
    private:
      /* Private methods */

      /* Private member variables */
    
    private slots:
      /* Private slots */
  };

2.1.6. Widget Names

  Every widget declared in a Qt Designer .ui file must have a short three or 
  four letter prefix that describes the widget's type.

       Widget Type           Prefix         Example
       ------------------------------------------------------------
       QCheckBox             chk            chkEnableFoo
       QComboBox             cmbo           cmboNames
       QFrame                frm            frmMain
       QGroupBox             grp            grpAdvanced
       QLabel                lbl            lblHeader
       QLineEdit             line           lineAddress
       QListView             lst            lstMessages
       QProgressBar          pbar           pbarDownload
       QPushButton           btn            btnClose
       QRadioButton          rdo            rdoSomeOption
       QSpinBox              spn            spnDial
       QTableView            tbl            tblSpreadsheet
       QTabWidget            tab            tabServerOptions
       QToolButton           btn            btnExit
       QTreeView             tree           treeFolders


2.2. Comments

  Comments should be standard C style comments. For example:

    int fooCounter;  /* Comment about counting foo */

  Multi-line comments should be formatted as:

    /*
     * This section of code is potentially confusing or ambiguous, so here is a
     * long comment that takes up multiple lines.
     */

2.3. Indentation
  
  All source code should follow these conventions:
  
    1. Tabs should be 2 characters wide. 
    2. Your editor should be set to replace tabs with spaces. 
    3. Lines should be less than 80 characters wide whenever possible.

2.4. Bracing

2.4.1. Methods

  Opening and closing braces for functions should be placed at column 1. For
  example:

     void 
     Foo::bar(void)
     {
     }

2.4.2. Loops

  Braces for loops should be formatted as follows:
     
     for (i = 0; i < 10; i++) {
       /* Do something ten times */
     }

2.4.3. if-else Statements

  The `else' portion of an if-else statement, if present, should begin on the
  same line as the closing brace of the `if' portion.

     if (foo == bar) {
       /* Do something */
     } else {
       /* My foo doesn't equal bar */
     }

  Braces may be omitted if there is only one line of code to be executed if
  the evaluated condition is true. For example, the following is permitted:

    if (foo == bar)
      return;

2.5. Parentheses

  
  int value = someObject.someMethod(foo, bar, baz);

2.6. Method Arguments

  const-correctness should be enforced whenever possible. Objects passed as
  arguments to a method should be passed by a const reference, as in the
  following example:

    void
    SomeClass::someMethod(const OtherClass &oc)
    {
      /* Do something with oc */
    }

2.7. Other

  Source files should end with a single blank line.