Add efacf056cd

dockerdoom/trunk/HACKING

@@ -0,0 +1,176 @@
+
+Coding style guidelines
+=======================
+
+The coding style guidelines for Chocolate Doom are designed to keep the
+style of the original source code.  This maintains consistency throughout
+the program, and does not require the original code to be changed. Some
+of these guidelines are stricter than what was done in the original
+source; follow these when writing new code only: there is no need to 
+change existing code to fit them.
+
+You should set tabs to _display_ as eight spaces, not four.  However, 
+_indentation_ should be four spaces.  If possible, do not use tab
+characters at all.  There is a utility called "expand" which will remove
+tab characters.  For the reasoning behind this, see:
+http://www.jwz.org/doc/tabs-vs-spaces.html
+
+Please write code to an 80 column limit so that it fits within a standard
+80 column terminal.
+
+Functions should be named like this: 'AB_FunctionName'.  The 'AB' prefix 
+denotes the subsystem (AM_ for automap, G_ for game, etc).  If a
+function is static, you can omit the prefix and just name it like
+'FunctionName'.  Functions and global variables should always be made 
+static if possible.
+
+Put '_t' on the end of types created with typedef.  Type names like this
+should be all lowercase and have the subsystem name at the start. An
+example of this is 'txt_window_t'.  When creating structures, always
+typedef them.
+
+Do not use Hungarian notation.
+
+Do not use the goto statement.
+
+Use C++-style comments, ie. '//' comments, not '/* ... */' comments.
+I don't care that this isn't standard ANSI C.
+
+Variables should be named like this: 'my_variable_name', not like this:
+'MyVariableName'.  In pointer variable declarations, place the '*' next 
+to the variable name, not the type.
+
+When using an if, do, while, or for statement, always use the { } braces
+even when they are not necessary.  For example, do this:
+
+    if (condition)
+    {
+        body;
+    }
+
+Not this:
+
+    if (condition)   // NO
+        body;
+
+Write code like this:
+
+typedef struct
+{
+    int member1;
+    char *member2;
+} my_structure_t;
+
+void FunctionName(int argument, int arg2, int arg3, int arg4, int arg5, 
+                  int arg6, int arg7)
+{
+    if (condition)
+    {
+        body;
+    }
+    else if (condition)
+    {
+        body;
+    }
+    else 
+    {
+        body;
+    }
+
+    if (very_long_condition_like_this_one_that_forces_a_line_break
+     && other_condition)
+    {
+        body;
+    }
+
+    switch (argument)
+    {
+        case FIRST:
+            code;
+            break;
+            
+        case SECOND:
+            code;
+            break;
+            
+        default:
+            break;
+    }
+
+    for (a=0; a<10; ++a)
+    {
+        loop_body;
+    }
+
+    while (a < 10)
+    {
+        loop_body;
+    }
+
+    do 
+    {
+
+    } while (condition);
+}
+
+Portability
+===========
+
+Chocolate Doom is designed to be cross-platform and work on different
+Operating Systems and processors.  Bear this in mind when writing code.
+
+Do not use the long type (its size differs across platforms; use 
+int or int64_t depending on which you want).
+
+Use Doom's byte data type for byte data. 'int' is assumed to be a
+32-bit integer, and 'short' is a 16-bit integer. You can also use the
+ISO C99 data types: intN_t and uintN_t where N is 8,16,32,64.
+
+Be careful with platform dependencies: do not use Windows API 
+functions, for example.  Use SDL where possible.
+
+Preprocessor #defines are set that can be used to identify the OS
+if necessary: _WIN32 for Windows and __MACOSX__ for MacOS X. Others
+are set through SDL.  Try to avoid this if possible.
+
+Be careful of endianness!  Doom has SHORT() and LONG() macros that
+do endianness conversion.  Never assume that integer types have a 
+particular byte ordering.  Similarly, never assume that fields 
+inside a structure are aligned in a particular way.  This is most 
+relevant when reading or writing data to a file or a network pipe.
+
+For signed integers, you shouldn't assume that (i >> n) is the same as
+(i / (1 << n)).  However, most processors handle bitshifts of signed
+integers properly, so it's not a huge problem.
+
+
+GNU GPL and licensing
+=====================
+
+All code submitted to the project must be licensed under the GNU GPL or a
+compatible license.  If you use code that you haven't 100% written 
+yourself, say so. Add a copyright header to the start of every file.  Use
+this template:
+
+// Emacs style mode select   -*- C++ -*-
+//-----------------------------------------------------------------------------
+//
+// Copyright(C) YEAR Author's name
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License
+// as published by the Free Software Foundation; either version 2
+// of the License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
+// 02111-1307, USA.
+
+# vim: tw=70
+