diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index 9594866ba..0b4077799 100644 --- a/Documentation/GNUmakefile +++ b/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 diff --git a/Documentation/coding-standards.tmpl.texi b/Documentation/coding-standards.tmpl.texi index 558499cc2..bd68c8d2f 100644 --- a/Documentation/coding-standards.tmpl.texi +++ b/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 -@section Error Handling +@node ChangeLog Entries, Coding Style, Introduction, Top +@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 +@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