Update

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@6298 72102866-910b-0410-8b05-ffd578937521

Documentation/GNUmakefile

@@ -31,7 +31,7 @@ include ../Version
 include ../config.mak
 
 # The documents to be generated
-DOCUMENT_NAME = gnustep-base 
+DOCUMENT_NAME = gnustep-base coding-standards
 
 # The text documents to be generated
 DOCUMENT_TEXT_NAME = \
@@ -44,6 +44,9 @@ version.tmpl.texi \
 gnustep-base.tmpl.texi \
 gnustep-zones.tmpl.texi
 
+coding-standards_TEXI_FILES = \
+coding-standards.tmpl.texi
+
 BUGS_TEXI_FILES = version.tmpl.texi
 BUGS_TEXT_MAIN = todo.tmpl.texi
 

Documentation/coding-standards.tmpl.texi

@@ -58,11 +58,13 @@ into another language, under the above conditions for modified versions.
 
 @menu
 * Introduction::                
+* ChangeLog Entries::           
+* Coding Style::                
 * Error Handling::              
 @end menu
 
 @c ******************************************************************
-@node Introduction, Error Handling, Top, Top
+@node Introduction, ChangeLog Entries, Top, Top
 @section Introduction
 
 This document explains the official coding standards which developers
@@ -70,9 +72,135 @@ for GNUstep base should follow. Note that these standards are in addition
 to GNU coding standards, not a replacement of them.
 
 @c ******************************************************************
-@node Error Handling,  , Introduction, Top
+@node ChangeLog Entries, Coding Style, Introduction, Top
-@section Error Handling
+@section ChangeLog Entries
 
+Always include a ChangeLog entry for work that you do. Look for the
+ChangeLog file in the current directory or look up to any number of
+parent directories. Typically there is one for each library.
+
+Emacs currently formats the header like this:
+
+@example
+2000-03-11  Adam Fedor  <fedor@@gnu.org>
+@end example
+
+and formats changes to functions/methods like this:
+
+@example
+* Source/NSSlider.m ([NSSlider -initWithFrame:]):
+@end example
+
+to which you add your own comments on the same line (with word
+wrapping). Although if you're making similar changes to multiple
+methods, it's ok to leave out the function/method name.
+
+Important: Changelog entries should state what was changed, not why it
+was changed. It's more appropriate to put that in the source code, where
+someone can find it, or in the documentation.
+
+@c ******************************************************************
+@node Coding Style, Error Handling, ChangeLog Entries, Top
+@section Coding Style
+
+The point is not what style is 'better' in the abstract -- it's what
+style is standard and readily usable by all the people wanting to
+use/work on GNUstep.  A reasonably good consistent style is better for
+collaborative work than a collection of styles irrespective of their
+individual merits.  If you commit changes that don't conform to the
+project standards, that just means that someone else will have a tedious
+time making the necessary corrections (or removing your changes).
+
+The GNUstep coding standards are essentially the same as the GNU coding 
+standards (@url{http://www.gnu.org/prep/standards_toc.html}), but here
+is a summary of the essentials.
+
+White space should be used for clarity throughout.  In particular,
+variable declarations should be separated from code by a blank line and
+function/method implementations should be separated by a blank line.
+
+Tabstops should be 8 spaces.
+
+All binary operators should be surrounded by white space with the
+exception of the comma (only a trailing white space).  Brackets should
+have space only before the leading bracket and after the trailing
+bracket (as in this example).  This applies to square brackets too.  The
+placement of curly brackets is part of the indentation rules. the
+correct GNU style is
+@example
+  if (...)
+    @{
+      ...
+    @}
+@end example
+
+For function implementations, the function names must begin on column zero
+(types on the preceeding line).  For function predeclaration, the types and
+the name should appear on the same line if possible.
+
+The curly brackets enclosing function and method implementations should be
+based in column 0.  Indentation is in steps of two spaces.
+
+Lines longer than 80 columns must be split up, if possible with the
+line wrap occurring immediately before an operator.  The wrapped lines
+are indented by two spaces form the original.
+
+Some things the standards seem to think are 'should' rather than 'must':
+
+Multiline comments should use @code{/* ... */} while single line
+comments may use @code{//}.
+
+In a C/ObjC variable declaration, the @samp{*} refers to the variable,
+not to the type, so you write
+@example
+  char	*foo;
+@end example
+not
+@example
+  char*	foo;
+@end example
+
+Using the latter approach encourages newbie programmers to thing they can
+declare two pointer variables by writing
+@example
+  char*	foo,bar;
+@end example
+when of course they need
+@example
+  char	*foo, *bar;
+@end example
+or (in my opinion better)
+@example
+  char	*foo;
+  char	*bar;
+@end example
+
+
+An exception to the indentation rules for Objective-C: We normally don't
+break long methods by indenting subsequent lines by two spaces, but make the
+parts of the method line up instead.
+The way to do this is indent so the colons line up.
+@example
+  [receiver doSomethingWith: firstArg
+                        and: secondArg
+                       also: thirdArg];
+@end example
+That's the style used mostly in the GNUstep code - and therefore the one I
+try to keep to.
+
+Finally, my own preference (not part of the standard in any way) is to
+generally use curly brackets for control constructs, event where only one line
+of code is involved
+@example
+  if (a)
+    @{
+      x = y;
+    @}
+@end example
+
+@c ******************************************************************
+@node Error Handling,  , Coding Style, Top
+@section Error Handling
 
 Initialization methods (e.g. -init) should, upon failure to
 initialize the class, deallocate itself and return nil. This may mean