r3861 - in trunk: . docs

[stw svn gnome org]

Author: stw
Date: 2006-08-22 11:09:35 -0400 (Tue, 22 Aug 2006)
New Revision: 3861

Added:
   trunk/docs/coding-style.doxi
Modified:
   trunk/ChangeLog
   trunk/docs/Makefile.am
   trunk/docs/beast-index.doxi
Log:
Tue Aug 22 17:02:50 2006  Stefan Westerfeld  <stefan space twc de>

	* docs/Makefile.am:
	* docs/beast-index.doxi:
	* docs/coding-style.doxi: Added a description of the beast coding
	style to the developer documentation.



Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog	2006-08-22 11:42:58 UTC (rev 3860)
+++ trunk/ChangeLog	2006-08-22 15:09:35 UTC (rev 3861)
@@ -1,3 +1,10 @@
+Tue Aug 22 17:02:50 2006  Stefan Westerfeld  <stefan space twc de>
+
+	* docs/Makefile.am:
+	* docs/beast-index.doxi:
+	* docs/coding-style.doxi: Added a description of the beast coding
+	style to the developer documentation.
+
 Tue Jul 18 01:43:25 2006  Tim Janik  <timj gtk org>
 
 	* web/scanimages.sh: skip ./.* files when scanning for images, this

Modified: trunk/docs/Makefile.am
===================================================================
--- trunk/docs/Makefile.am	2006-08-22 11:42:58 UTC (rev 3860)
+++ trunk/docs/Makefile.am	2006-08-22 15:09:35 UTC (rev 3861)
@@ -29,6 +29,7 @@
 	html/bsescm.1.html			\
 	html/sfidl.1.html			\
 	html/bse.5.html				\
+	html/coding-style.html			\
 )
 CLEANFILES += ${HTML_TARGETS}
 STYLE_TARGETS = $(strip				\
@@ -222,6 +223,7 @@
 	bsescm.1.doxi		\
 	plugin-devel.doxi	\
 	sfidl.1.doxi		\
+	coding-style.doxi	\
 )
 
 EXTRA_DIST += $(strip		\

Modified: trunk/docs/beast-index.doxi
===================================================================
--- trunk/docs/beast-index.doxi	2006-08-22 11:42:58 UTC (rev 3860)
+++ trunk/docs/beast-index.doxi	2006-08-22 15:09:35 UTC (rev 3861)
@@ -28,6 +28,7 @@
 @item @uri{ top_webdir/architecture.html,	BEAST Architecture}
 @item @uri{ top_webdir/plugin-devel.html,	Plugin Development}
 @item @uri{ top_webdir/sfidl-manual.html,	SFIDL - Manual}
+ item @uri{ top_webdir/coding-style.html,	BEAST Coding Style}
 @item @uri{ top_webdir/engine-mplan.html,	DSP Synthesis Engine} (plain text notes)
 @done
 

Added: trunk/docs/coding-style.doxi
===================================================================
--- trunk/docs/coding-style.doxi	2006-08-22 11:42:58 UTC (rev 3860)
+++ trunk/docs/coding-style.doxi	2006-08-22 15:09:35 UTC (rev 3861)
@@ -0,0 +1,226 @@
+ doxer_dnl
+ doxer_set{rvstamp,parse_date} $Date: 2006/02/21 00:28:59 $
+ include @doxer_get{DOXI_INCLUDE_FILE}
+ doxer_set{title}	BEAST - Coding Style
+
+ titlesection
+ doctitle		@beast - Coding Style
+ *
+ docauthor              Tim Janik
+ docauthor              Stefan Westerfeld
+ *
+ center 		Document revised: @doxer_get{rvstamp}
+ *
+
+This document provides a list of rules that need to be followed when writing
+code that become part of @beast. As the development of a consistent coding
+style is work in progress, these rules are not comprehensive. We also
+acknowledge that not all code that is part of @beast currently follows this
+coding style guide.
+
+However, everything that is in this file has been negotiated, and new code must
+follow each of these rules. Where no explicit rule exists, try to follow
+what existing code does, or ask, when in doubt.
+
+ tocsection Table of Contents
+
+ section Indentation and Formatting
+
+ subsection Function Return Types are written on a Separate Line
+
+This rule only applies for the implementation of functions, not for the function prototype.
+
+ emph{Reasons:}
+ itemize
+ item This makes reading the actual function name quickly easier, because all function names
+      start at the same column
+ done
+
+ emph{Code Example:}
+ example
+bool
+does_the_universe_still_exist()
+{
+  return true;
+}
+
+template<class T> bool
+frobify_two_things (const T &thing1,
+                    const T &thing2)
+{
+  [...]
+}
+
+class Foo
+{
+  bool m_alive;
+public:
+  static bool
+  is_any_foo_alive()
+  {
+    [...]
+  }
+  bool
+  is_alive() const
+  {
+    return m_alive;
+  }
+  [...]
+};
+
+ done
+
+ subsection Multiline Comments
+
+There are generally two kinds of multiline comments: documentation comments and
+non-documentation comments. The following code example show that documentation
+comments get an extra line, which starts the documentation comment, whereas
+ordinary comments may not have an extra new line.
+
+ emph{Code Example:}
+ example
+/**
+ * This function is checks whether the universe still exists; however it is
+ * unclear how a caller could call it if the universe no longer exists, so you
+ * probably won't need it.
+ */
+bool
+does_the_universe_still_exist()
+{
+  /* We can assume that if the program still runs, then the universe can
+   * not possibly be gone.
+   */
+  return true;
+}
+ done
+
+ subsection References and Pointers are declared next to the Identifier
+
+ emph{Reasons:}
+ itemize
+ item When declaring more than one variable, the pointer / reference symbol (* or &) will only affect the first
+      declaration. Thus it is better to put this symbol next to the identifier, to avoid mistakes.
+ done
+
+ emph{Code Example:}
+ example
+struct Foo
+{
+  char    *x;
+  string  &y;
+  Foo     *z;
+};
+
+void bar (Foo          &foo1,
+	  const string &y)
+{
+  char *x, *y, *z;
+  const string &bar = foo1.y;
+}
+ done
+
+ subsection Constructor Initializer Indentation
+
+The initializers following a constructor should be indented like this:
+
+ emph{Code Example:}
+ example
+class Foo : public Bar
+{
+  int	      m_x;
+  int	      m_y;
+  vector<int> m_some_integers;
+public:
+  Foo (const string &bar_name,
+       int           x,
+       int           y) :
+    Bar (bar_name),
+    m_x (x),
+    m_y (y),
+    m_z (x * y)
+  {
+  }
+  [...]
+};
+ done
+
+It is important that the colon (":") is placed after the constructor declaration,
+whereas the member initializers (or chained parent constructors) are placed on
+the next lines.
+
+ section Names
+
+ subsection Functions, Methods, Members, Arguments and Local Variables are written as @code{lower_case_underscore_names}
+
+ emph{Code Example:}
+ example
+guint
+add_one (guint some_number)
+{
+  return some_number + 1;
+}
+ done
+
+ subsection Type Names are written as @code{MixedCaseNames}
+
+ emph{Code Example:}
+ example
+typedef float SampleType;
+
+class HashTable
+{
+  [...]
+};
+ done
+
+ subsection Class Members are prefixed with @code{m_}
+
+ emph{Reasons:}
+ itemize
+ item This is meant to distinguish class members from local variables,
+      arguments or function names; for a constructor for instance you often get an
+      argument x, and want to initialize the corresponding member; instead of writing
+      @code{Constructor (int x) : x (x)} which may be misleading, you can write
+      @code{Constructor (int x) : m_x (x)}
+ done
+
+ emph{Code Example:}
+ example
+class IntArray
+{
+  vector<int> m_integers;
+public:
+  IntArray (guint n_integers) :
+    m_integers (n_integers)
+  {
+  }
+  [...]
+}
+ done
+
+ section C++ References
+
+ subsection Out Arguments of Functions that are Non Object Types are passed by Pointer, not by Reference
+
+ emph{Reasons:}
+ itemize
+ item This is meant to improve the readability of the code (you can see that the value is being modified)
+ item It makes understanding the code easier for C programmers, which may not be used to references
+ done
+
+Every output argument that has a type that can be found in C (pointer, float, int, ...) may not be
+passed by reference, but must be passed by pointer. This rule does not apply to C++ objects which
+may be passed by reference.
+
+ emph{Code Example:}
+ example
+bool
+parse_xyz (const string &input,
+           float        *x,
+	   float        *y,
+	   float        *z)
+{
+  [... C++ Code that parses the input string, returns true
+       on success and fills x, y, and z with the parsed values ... ]
+}
+ done