style docs

panda/src/doc/coding-style.txt

@@ -0,0 +1,136 @@
+Almost any programming language gives a considerable amount of freedom
+to the programmer in style conventions.  Most programmers eventually
+develop a personal style and use it as they develop code.
+
+When multiple programmers are working together on one project, this
+can lead to multiple competing styles appearing throughout the code.
+This is not the end of the world, but it does tend to make the code
+more difficult to read and maintain if common style conventions are
+not followed throughout.
+
+It is much better if all programmers can agree to use the same style
+when working together on the same body of work.  It makes reading,
+understanding, and extending the existing code much easier and faster
+for everyone involved.  This is akin to all of the animators on a
+feature film training themselves to draw in one consistent style
+throughout the film.
+
+
+Often, there is no strong reason to prefer one style over another,
+except that at the end of the day just one must be chosen.
+
+
+The following lays out the conventions that we have agreed to use
+within Panda.  Most of these conventions originated from an
+amalgamation of the different styles of the first three programmers to
+do major development in Panda.  The decisions were often arbitrary,
+and some may object to the particular choices that were made.
+Although discussions about the ideal style for future work are still
+welcome, considerable code has already been written using these
+existing conventions, and the most important goal of this effort is
+consistency.  Thus, changing the style at this point would require
+changing all of the existing code as well.
+
+Note that not all existing Panda code follows these conventions.  This
+is unfortunate, but it in no way constitutes an argument in favor of
+abandoning the conventions.  Rather, it means we should make an effort
+to bring the older code into compliance as we have the opportunity.
+
+Naturally, these conventions only apply to C and C++ code; a
+completely different set of conventions has been established for
+Python code for the project, and those conventions will not be
+discussed here.
+
+
+SPACING:
+
+No tab characters should ever appear in a C++ file; we use only space
+characters to achieve the appropriate indentation.  Most editors can
+be configured to use spaces instead of tabs.
+
+We use two-character indentation.  That is, each nested level of
+indentation is two characters further to the right than the enclosing
+level.
+
+Spaces should generally surround operators, e.g. i + 1 instead of i+1.
+Spaces follow commas in a parameter list, and semicolons in a for
+statement.  Spaces are not placed immediately within parentheses;
+e.g. foo(a, b) rather than foo( a,b ).
+
+Resist writing lines of code that extend beyond 80 columns; instead,
+fold a long line when possible.  Occasionally a line cannot be easily
+folded and remain readable, so this should be taken as more of a
+suggestion than a fixed rule, but most lines can easily be made to fit
+within 80 columns.
+
+Comments should never extend beyond 80 columns, especially sentence or
+paragraph comments that appear on a line or lines by themselves.
+These should generally be wordwrapped within 72 columns.  Any smart
+editor can do this easily.
+
+
+CURLY BRACES:
+
+In general, the opening curly brace for a block of text trails the
+line that introduces it, and the matching curly brace is on a line by
+itself, lined up with the start of the introducing line, e.g.:
+
+  for (int i = 0; i < 10; i++) {
+    ...
+  }
+
+Commands like if, while, and for should always use curly braces, even
+if they only enclose one command.  That is, do this:
+
+  if (foo) {
+    bar();
+  }
+
+instead of this:
+
+  if (foo)
+    bar();
+
+
+NAMING:
+
+Class names are mixed case with an initial capital, e.g. MyNewClass.
+Each different class (except nested classes, of course) is defined in
+its own header file named the same as the class itself, but with the
+first letter lowercase, e.g. myNewClass.h.
+
+Typedef names and other type names follow the same convention as class
+names: mixed case with an initial capital.  These need not be defined
+in their own header file, but usually typedef names will be scoped
+within some enclosing class.
+
+Local variable names are lowercase with an underscore delimiting
+words: my_value.  Class data members, including static data members,
+are the same, but with a leading underscore: _my_data_member.  We do
+not use Hungarian notation.
+
+Class method names, as well as standalone function names, are
+lowercase with a delimiting underscore, just like local variable
+names: my_function().
+
+
+LANGUAGE CONSTRUCTS:
+
+Prefer C++ constructs over equivalent C constructs when writing C++
+code.  For instance, use:
+
+  static const int buffer_size = 1024;
+
+instead of:
+
+  #define BUFFER_SIZE 1024
+
+
+Resist using brand-new C++ features that are not broadly supported by
+compilers.  One of our goals in Panda is ease of distribution to a
+wide range of platform; this goal is thwarted if only a few compilers
+may be used.
+
+
+More examples of the agreed coding style may be found in
+panda/src/doc/sampleClass.* .

panda/src/doc/sampleClass.h

@@ -24,13 +24,13 @@
 // generally one .h file per class, with the .h file named after the
 // class but the first letter lowercase.
 
-#include <pandabase.h>
+#include "pandabase.h"
 
 #include "localHeaderFile.h"
 #include "anotherLocalHeaderFile.h"
 
-#include <typedObject.h>
-#include <anotherPandaHeaderFile.h>
+#include "typedObject.h"
+#include "anotherPandaHeaderFile.h"
 
 #include <systemHeaderFile.h>