[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[vidalia-svn] r2708: Move Vidalia's semi-documented coding style into a HACKING d (in vidalia: . trunk trunk/doc)
Author: edmanm
Date: 2008-06-13 01:48:59 -0400 (Fri, 13 Jun 2008)
New Revision: 2708
Added:
vidalia/trunk/HACKING
Removed:
vidalia/trunk/doc/coding-spec.txt
Modified:
vidalia/
Log:
r539@thebe: edmanm | 2008-06-13 01:49:40 -0400
Move Vidalia's semi-documented coding style into a HACKING document, and try
to specify a few more things.
Property changes on: vidalia
___________________________________________________________________
svk:merge ticket from /local/vidalia [r539] on 45a62a8a-8088-484c-baad-c7b3e776dd32
Added: vidalia/trunk/HACKING
===================================================================
--- vidalia/trunk/HACKING (rev 0)
+++ vidalia/trunk/HACKING 2008-06-13 05:48:59 UTC (rev 2708)
@@ -0,0 +1,265 @@
+$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.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.
+
Property changes on: vidalia/trunk/HACKING
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Deleted: vidalia/trunk/doc/coding-spec.txt