# Appendix

## Code Style

I know any discussion of coding styles leads to strong opinions, so I'll state simply I follow the GNU Coding Standards. Where there is some flexibility as to the location of braces, I prefer mine on the end of a line when using an if, while, or do statement. I find this more compact style easier to read and parse by eye. I'm also a big fan of always using braces around if statements, even if they're one liners.

Here's my tweaked style settings for Emacs, the one true editor to rule them all.

          (defconst my-style
              '((c-tab-always-indent   . t)
               (c-auto-newline	   . t)
               (c-hanging-braces-alist . (
    				   (brace-list-intro)
    				   (namespace-open)
    				   (inline-open)
    				   (block-open)
    				   (brace-list-open)
    				   (brace-list-close)
    				   (brace-entry-open)
    				   (brace-else-brace)
    				   (brace-elseif-brace)
    				   (class-open after)
    				   (class-close)
    				   (defun-open after)
    				   (defun-close)
    				   (extern-lang-open)
    				   (inexpr-class-open)
    				   (statement-open)
    				   (substatement-open)
    				   (inexpr-class-close)))
                (c-hanging-colons-alist . ((member-init-intro before)
                                       (inher-intro)
                                       (case-label after)
                                       (label after)
                                       (access-label after)))
                (c-offsets-alist	. (
    				   (innamespace . 0)
                                       (case-label  . 2)
    				   ))
                (c-cleanup-list	. (
    				   (scope-operator)
    				   (empty-defun-braces)
    				   (brace-else-brace)
    				   (brace-elseif-brace)
    				   (defun-close-semi)
    				   (list-close-comma)
    				   )
    				)
        ;; no automatic newlines after ';' if following line non-blank or inside
        ;; one-line inline methods
        (add-to-list 'c-hanging-semi&comma-criteria
    		 'c-semi&comma-no-newlines-before-nonblanks)
        (add-to-list 'c-hanging-semi&comma-criteria
    		 'c-semi&comma-no-newlines-for-oneline-inliners)
    ;    (knr-argdecl-intro . -)
        (c-echo-syntactic-information-p . t)
        )
      "My GNU Programming Style")

Another coding consideration: comments are good! Over commenting isn't good. Here is an over commented example:

    	counter++;		// increment counter

Gnash also uses Doxygen style comments. These are processed by Doxygen when building a cross reference of all the classes, and is a good way to help push internals documentation from the depths of the code into documentation where it can be seen by others.

Doxygen style comments for C++ code involves simply using three slashes /// instead of the standard two slashes // used for C++ comments. Here's a short comment block for the XML::cloneNode() method:

    	/// \brief copy a node
    	///
    	/// Method; constructs and returns a new XML node of the same type,
    	/// name, value, and attributes as the specified XML object. If deep
    	/// is set to true, all child nodes are recursively cloned, resulting
    	/// in an exact copy of the original object's document tree.
    	XMLNode &
    	XML::cloneNode(XMLNode &newnode, bool deep) {
    	...
    	}

The \brief keyword means that the text becomes associated when listing all the classes on the generated web pages. The text after the blank link becomes the detailed description which appears on the generated web page for that class and method.