====== Coding Style ======
===== Introduction ======
This document describes my personal coding style, hopefully consistent for all programming languages I use.

Sources:
  * [[http://fluxbox.cvs.sourceforge.net/viewvc/fluxbox/fluxbox/doc/Coding_style|Fluxbox Coding Style]]
  * [[http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html|Code Conventions for Java]]
  * PHP Code Conventions??

===== Indentation ==

  * 4 spaces for indentation
  * No hard tabs!
  * If hard tabs are unavoidable, they have to be set to 8 spaces
  * Lines not longer than 80 characters

===== Identifier Naming ==

  - Use lowercase for variables and use ''_'' to separate names, i.e no camel case for variables.
  - All constants must be in Upper case letters.
  - Class names always starts with an uppercase letter and use camel case rather than ''_''
  - Data members of classes are prefixed by ''m_'' (Not necessary when you have to use ''this'' anyway)
  - Static variables or class data members are prefixed with ''s_''

===== Doxygen ======
==== Links ====

[[http://www.stack.nl/~dimitri/doxygen/manual.html|Manual]] [[http://www.stack.nl/~dimitri/doxygen/commands.html|Special Commands]] [[http://www.stack.nl/~dimitri/doxygen/config.html|Configuration]]


==== Startup ==

  - ''doxygen -g [config_file]'' - generate a Doxyfile
  - ''mv Doxyfile Doxyfile.all''
  - ''touch Doxyfile''
  - Copy the settings to change from Doxyfile.all to Doxyfile
  - ''doxygen'' -- create the documentation

==== Important Config Settings ====

<code bash>
PROJECT_NAME           = "plcext"
#PROJECT_NUMBER         = 47.11
JAVADOC_AUTOBRIEF      = YES
OPTIMIZE_OUTPUT_FOR_C  = YES
#EXTRACT_ALL            = YES # important for c
INPUT                  = "V/plcext.386/Source" "V/plcext.386/Include/SMC"
FILE_PATTERNS          = "*.h"  # important for c
HTML_HEADER            = "doc/doxyheader.html"
GENERATE_LATEX         = NO
#OUTPUT_LANGUAGE        = "German"
OUTPUT_DIRECTORY       = "/var/www/htdocs/doxygen/plcext"
SORT_MEMBER_DOCS       = NO
DISTRIBUTE_GROUP_DOC   = YES
</code>



===== Documentation Comments ======

In c and c++ documentation comments go only to the header files, not to the source files, because...
  - Header files are available in libraries too
  - www.gtkmm.org does it in the same way ;-)

<code c>
/** Liest bitweise von einem Plc-Datenwort.
    Abkuerzung fuer PlcDwBits_io() mit doSet=false
    @param  this  Zeiger auf die Objektdaten
    @param  value Quelle fuer die Bits die in der Maske nicht gesetzt sind
    @see    PlcDwBits_io()
    @return >=0: Ergebnis | -1: Fehler beim Zugriff aufs Datenwort
    */
int PlcDwBits_get(const PlcDwBits *this, unsigned short value);
</code>

or short form:
<code c>
/** @todo Doc me! Untested! */
PlcDwRange *PlcDwRange_init(PlcDwRange *this, int db, int dw,
                            int len, unsigned short *values);
</code>

To doc a file:
<code c>
/** @file main.c
    Project:  appTemplate
    Target:   Kaeser Sigma Air Manager on Rmos3 v3.20 on Elan520
    Author:   Stefan Beckert
    Version:  $Id$
    Compiler: CAD-UL ANSI C Cross Optimizing Compiler - Version: V701D
    
    Description:
        Blah blah
    
    Todo:
        Blah blah
    */
</code>

===== Implementation Comments ==

<code c>
var ths= buf[0].getElementsByTagName("th"); // all thead th elements

// get real number of columns (take colspans of th's into account)
for (var col=0; col<ths.length; col++) {
    var th= ths[col];
    var colsp= th.getAttribute('colspan');
    if (!colsp) colsp= 1;
    for (var i=0; i<colsp; i++) this.thIdx.push(col);

    /* Store table header text and set the sort events
        Firefox supports setting event handling function like this:
        th.setAttribute('onclick', 'ts_doSort(...)') but IE6 not!
        */
    if (th.getAttribute('ts_sortable') != 'false') {
        this.thText[col]= th.innerHTML;
        var ih = '<span';
</code>

===== Hungarian Notation? ==

Some facts about hungarian notation:

  * Though HN originally [[wp>Hungarian_Notation#History|came from Microsoft]] they now [[http://msdn2.microsoft.com/en-us/library/ms229045.aspx|discourage]] the use of HN.
  * Neigther in the [[javaref>api/|Java API]] nor in the [[javatut>|Java Tutorial]] HN is used anywhere. How to find reasonable non-ambiguous HN prefixes with almost 4000 different Classes and Interfaces with long names like AbstractColorChooserPanel in the Java API?
  * Bjarne Stroustrup who developed C++ is [[http://en.wikipedia.org/wiki/Hungarian_Notation#Notable_opinions|against]] HN.