Add changes file for the torrc parsing patch
[vidalia.git] / HACKING
1 $Id$
2
3               Vidalia Coding and Repository Specification
4
5 0. Introduction
6   
7   This document is intended to loosely specify coding conventions followed in
8   Vidalia code, as well as conventions used in Vidalia's Subversion
9   repository.
10
11 1. Repository Organization
12
13 1.1. Subversion Location
14   
15   Vidalia's repository supports anonymous checkout. You can grab the most
16   recent revision of Vidalia's source code via:
17
18     svn co https://svn.vidalia-project.net/svn/vidalia/trunk/ vidalia
19
20 1.2 Directory Layout
21
22   The following are the current directories found in Vidalia's SVN repository
23   and a general decription of their intended contents:
24  
25   From https://svn.vidalia-project.net/svn/vidalia:
26
27      ./tags:
28
29         Snapshots of all Vidalia releases will be contained in a sub-directory
30         of ./tags, named according to the Vidalia version specification.
31         For example, ./tags/vidalia-0.0.1/ would contain the 0.0.1 release of
32         Vidalia.
33   
34      ./trunk:
35
36         Contains the main branch of Vidalia's source code.
37
38      ./trunk/doc:
39
40         Contains Vidalia's documentation, such as specifications and todo
41         lists.
42
43      ./trunk/src:
44
45         All Vidalia source code will be contained under this directory.
46
47      ./trunk/src/torcontrol:
48
49         Code in this directory implements Tor's control protocol. It also
50         handles things such as starting and stopping Tor and checking the
51         status of the Tor process.
52
53      ./trunk/src/vidalia:
54
55        This directory contains code that implements the GUI components of
56        Vidalia. Whenever possible and sane, each component should be placed in
57        an appropriately-named subdirectory of ./trunk/src/vidalia.
58
59     ./trunk/src/vidalia/res:
60
61        All GUI-related resource files, such as images, should go in this
62        directory. Images should be placed in sub-directories appropriate for
63        their image size. For example, 16x16 images would go in
64        ./trunk/src/vidalia/res/16x16/
65        
66     ./trunk/src/common:
67
68        If a source file doesn't belong in the previous directories, it should
69        go here. This directory will containg various utility functions, such
70        as date or time parsing, custom string manipulation functions, etc. If
71        a particular utility has multiple source files, they should all be
72        placed in a subdirectory. For example, if there were several source
73        files that implemented various string manipulation functions, they
74        could go in ./trunk/src/common/string.
75
76 2. Coding Conventions
77   
78   This section aims to provide a small overview of coding conventions used in
79   Vidalia, to keep the look of the code consistent between developers and
80   contributors. Since it would be impossible to specify all aspects of coding
81   here, common sense should be employed for things not specified below.
82
83 2.1. Naming Conventions
84
85 2.1.1. Source File Names
86   
87   C++ classes should be divided in to a <ClassName>.h file, containing the
88   class declarations, and a <ClassName>.cpp file containg the class
89   implementation. Each .cpp file should implement only one public class.
90   Filenames containing a class should follow the same "CamelCase"
91   capitalization format as the class name itself.
92
93   Source files that do not implement a C++ class should be named logically and
94   in all lowercase letters. For example, threading-related code would go in
95   thread.cpp and thread.h. 
96
97
98 2.1.2. Class Names
99
100   Class names should begin with a capital letter. If a name is a combination
101   of distinct words, each word should be capitalized. The purpose of the class
102   should be explained in Doxygen tags. Example:
103
104     /** A brief description of MyClass. */
105     /**
106      * Alternatively, here is a more detailed description of MyClass.
107      */
108     class MyClass
109     {
110     };
111
112
113   Doxygen-style comments should be used above each method declaration in
114   the class.
115
116 2.1.3. Method Names
117   
118   Method names should begin with a lower case letter. If a method name is a
119   combination of distinct words, each word should be capitalized. Methods
120   should have descriptions of their purpose. Example:
121
122     /* Description of what someMethod does. */
123     int 
124     MyClass::someMethod(int foo)
125     {
126     }
127   
128   Doxygen tags should be used for comments above the method definition
129   ONLY if the method's declaration in the class header file does not
130   already have a Doxygen-style comments.
131
132   Note that the method's return type is declared on a line by itself. Private
133   member function should NOT have an underscore prepended to their name.
134
135 2.1.4. Variable Names
136
137   Variable names should follow a convention similar to method names. Variable
138   names should be descriptive if their purpose is non-obvious.
139
140   Variables that are members of a class should have a leading underscore to
141   distinguish them from local variables in a method. Member variables should
142   also have a description of their purpose in Doxygen tags. For example:
143
144   /** A brief description of MyClass */
145   
146   /**
147    * A more detailed description of MyClass.
148    */
149   class MyClass
150   {
151     private:
152       int _myVariable; /**< Description of what _myVariable is */
153   };
154  
155 2.1.5. Ordering of Method and Member Variable Declarations
156
157   Class member method and variable declarations should be arranged according
158   to decreasing order of visibility.
159
160   class MyClass : public QObject
161   {
162     Q_OBJECT
163     
164     public:
165       /* Public enums */
166
167       /* Public methods */
168   
169     public slots:
170       /* Public slots */
171
172     signals:
173       /* Signals emitted by this class */
174     
175     protected:
176       /* Protected methods */
177
178       /* Protected member variables */
179
180     protected slots:
181       /* Protected slots */
182     
183     private:
184       /* Private methods */
185
186       /* Private member variables */
187     
188     private slots:
189       /* Private slots */
190   };
191
192 2.1.6. Widget Names
193
194   Every widget declared in a Qt Designer .ui file must have a short three or 
195   four letter prefix that describes the widget's type.
196
197        Widget Type           Prefix         Example
198        ------------------------------------------------------------
199        QCheckBox             chk            chkEnableFoo
200        QComboBox             cmbo           cmboNames
201        QDialogButtonBox       -             buttonBox
202        QFrame                frm            frmMain
203        QGroupBox             grp            grpAdvanced
204        QLabel                lbl            lblHeader
205        QLineEdit             line           lineAddress
206        QListView             lst            lstMessages
207        QProgressBar          pbar           pbarDownload
208                               -             progressBar
209        QPushButton           btn            btnClose
210        QRadioButton          rdo            rdoSomeOption
211        QSpinBox              spn            spnDial
212        QTableView            tbl            tblSpreadsheet
213        QTabWidget            tab            tabServerOptions
214        QToolButton           btn            btnExit
215        QTreeView             tree           treeFolders
216
217
218 2.2. Comments
219
220   Comments should be standard C style comments. For example:
221
222     int fooCounter;  /* Comment about counting foo */
223
224   Multi-line comments should be formatted as:
225
226     /*
227      * This section of code is potentially confusing or ambiguous, so here is a
228      * long comment that takes up multiple lines.
229      */
230
231 2.3. Indentation
232   
233   All source code should follow these conventions:
234   
235     1. Tabs should be 2 characters wide. 
236     2. Your editor should be set to replace tabs with spaces. 
237     3. Lines should be less than 80 characters wide whenever possible.
238
239 2.4. Bracing
240
241 2.4.1. Methods
242
243   Opening and closing braces for functions should be placed at column 1. For
244   example:
245
246      void 
247      Foo::bar(void)
248      {
249      }
250
251 2.4.2. Loops
252
253   Braces for loops should be formatted as follows:
254      
255      for (i = 0; i < 10; i++) {
256        /* Do something ten times */
257      }
258
259 2.4.3. if-else Statements
260
261   The `else' portion of an if-else statement, if present, should begin on the
262   same line as the closing brace of the `if' portion.
263
264      if (foo == bar) {
265        /* Do something */
266      } else {
267        /* My foo doesn't equal bar */
268      }
269
270   Braces may be omitted if there is only one line of code to be executed if
271   the evaluated condition is true. For example, the following is permitted:
272
273     if (foo == bar)
274       return;
275
276 2.5. Parentheses
277
278   There should NOT be a space between an opening parenthesis and the
279   first argument, nor between the end of the last argument and a closing
280   parenthesis.
281   
282     int value = someObject.someMethod(foo, bar, baz);
283
284 2.6. Method Arguments
285
286   const-correctness should be enforced whenever possible. Objects passed as
287   arguments to a method should be passed by a const reference, as in the
288   following example:
289
290     void
291     SomeClass::someMethod(const OtherClass &oc)
292     {
293       /* Do something with oc */
294     }
295
296 2.7. Other
297
298   Source files should end with a single blank line.
299