wxOS2 additional stylistic and coding standards.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@10114 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/src/os2/standard.txt b/src/os2/standard.txt
new file mode 100644 (file)
index 0000000..912fc2f
--- /dev/null
+++ b/src/os2/standard.txt
@@ -0,0 +1,144 @@
+This is just a note explaining the additional coding standards I use in
+the OS/2 port.  These are in addition to the project standards and are designed
+to enhance the readability and maintenance of the code.  There are two main
+standards I employ and few minor ones.  Indentation/columner aligned code
+and variable naming are the key conventions I use.
+
+Indentations allow for a very clean look and feel to the code as well as assisting
+in debugging.  This is really more a stylistic option that just makes the code
+look better and easier to read.  Basically I put the data declaration type to the left
+and the variable in column 37 or 41 (9 or ten 4 space tabs from the left margin).
+All indentations are multiples of 4. Probably the most important indentation
+standard I use concerns if/else constructs.
+
+I find code like:
+
+    if (var == 1)  MyFunc();
+    else return FALSE;
+
+and:
+    if (eVal == ENUM1) {
+        DoSomething();
+        DoSomethingElse();
+    } else if (eVal == ENUM2) {
+        DoAnotherThing();
+        DoSomethingElse();
+    } else return FALSE;
+
+to be ugly, hard to match openning and closing braces, and a bit of pain for
+some debuggers.  So I use this instead:
+
+    if (var == 1)
+        MyFunc();
+    else
+        return FALSE;
+
+and:
+    if (eVal == ENUM1)
+    {
+        DoSomething();
+        DoSomethingElse();
+    }
+    else if (eVal == ENUM2)
+    {
+        DoAnotherThing();
+        DoSomethingElse();
+    }
+    else
+        return FALSE;
+
+This is infinitely more readable, allows for easy matchup of openning and
+closing braces and is friendlier to debuggers.
+
+Another issue in this category is the function call with large number of parameters.
+Especially if  some of the parameters are function calls themselves.  I find code
+like
+
+    MyCall2( param, someotherparam, CallAnotherProc(), CallYetAnotherProc(), param2, param3, Yourproc(), param4);
+
+to be ugly and hard on some debuggers and some editors/printers don't like trailing
+out over 100 columns.  I prefer something like this:
+
+    MyCall2( param
+            ,someotherparam
+            ,CallAnotherProc()
+            ,CallYetAnotherProc()
+            ,param2
+            ,param3
+            ,Yourproc()
+            ,param4
+           );
+
+Much more readable, and debugger and editor friendly.
+
+Like I said above all that is mostly style, but below is something that I find
+partiuclarly irritating about a lot of code in this and other public projects,
+the haphazard and lazy use of variable names.  How often have you found yourself
+deep down in a large function and run across something like xd = p or CallProc(val, val2)
+and you have no idea what xd or p is or where val or val2 are delcared and you
+have to go spend time to find them?  Waste of time.  Or something like
+if (val).  Is val an integer you are testing for nonzero or a pointer for nonNULL?
+You have to back up somewhere or into a class header to find it in order to know.
+Coders that use one or two character identifiers in anything other than loop
+controls are basically just lazy.
+
+To alleviate a lot of this poor readability I have instuted the following naming
+conventions in this port.
+
+Class data members are alway preceded with a m_.
+
+Datatype prefixes are as follows:
+
+    n  -- int, short
+    l  -- long, size_t (specific 32 bit integer)
+    ll -- longlong (64 bit integer)
+    f  -- float
+    d  -- double
+    w  -- word
+    dw -- dword
+    h  -- handle
+    u  -- unsigned
+    c  -- char/byte (8 bit)
+    z  -- char* string
+    s  -- string class string
+    p  -- pointer
+    q  -- smart (counted) pointer
+    r  -- reference
+    a  -- array
+    v  -- user or library defined datatype (can be a struct, typedef, or even
+          a class variable).
+
+So a class member that is a pointer to something is m_pVar.  A pointer to an
+unsigned long is a pulVal.  rsVal is a reference to a string.
+
+Also I use as many desriptive names as possible.  So an int for a box width is
+nWidth, not w or x.  An unsigned long for a datalength is ulLength not len or l.
+A class member that is a pointer to client window is m_pClient or
+m_pvClient, not just client. A wxBrush is vBrush or a handle to a brush is
+hBrush as opposed to br or hbr and if they were class members then m_vBrush and
+m_hBrush.
+
+Some other things you will not find in this port are things like:
+
+Large numbers of nested function calls on one line or if statement.
+
+Obtuse nonsense like while (*d++ = *s).  What is that?  Instead you will see
+
+    while (*d != '\0')
+    {
+        .
+        .
+        .
+        *d++;
+        *d = s;
+    }
+
+I hope you will find wxOS2 extremely easy to read, follow, and debug. Unlike
+a lot of programmers I find writing code to be every bit as much a work of
+art as of science.  The neatness and appearance of one's code tells a every
+bit as much about the person writing it as its functionality and correctness.
+
+Dave Webster,
+Struggling OS/2 developer.
+
+