XML-LibXML "Hacking"-Related Issues
========================================
Shlomi Fish <shlomif@cpan.org>
:Date: 2009-08-14
:Revision: $Id: HACKING.txt 3943 2011-06-29 10:04:01Z shlomif $

Perl Style Guidelines
---------------------

Use Test::More for test scripts while using Test::Count annotations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One should use Test::More for new test scripts, while using Test::Count
( http://beta.metacpan.org/module/Test::Count ) "# TEST" annotations. Some
of the old test scripts under +t/*.t+ are still using Test.pm, but it should
not be used for new code.

Any bug fixes or feature addition patches should be accompanied with
a test script to test the code.

Avoid trailing statement modifiers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One should not use trailing "if"s "while"s "until"s, etc.

Bad:

----------------
print "Hello\n" if $cond;
----------------

Good:

----------------
if ($cond)
{
    print "Hello\n";
}
----------------

Avoid until and unless
~~~~~~~~~~~~~~~~~~~~~~

"until" and "unless" should be spelled using "if !" or "while !".

Other elements to avoid
~~~~~~~~~~~~~~~~~~~~~~~

See http://perl-begin.org/tutorials/bad-elements/

C Style Guidelines
------------------

Here are some style guidelines for new code to be accepted into XML-LibXML:

4 Spaces for Indentation
~~~~~~~~~~~~~~~~~~~~~~~~

The source code should be kept free of horizontal
tabs (\t, HT, \x09) and use spaces alone. Furthermore, there should be
a 4 wide space indentation inside blocks:

----------------
if (COND())
{
    int i;

    printf("%s\n", "COND() is successful!");

    for (i=0 ; i < 10 ; i++)
    {
        ...
    }
}
----------------

Curly Braces Alignment
~~~~~~~~~~~~~~~~~~~~~~

The opening curly brace of an if-statement or a for-statement should be
placed below the statement on the same level as the other line, and the
inner block indented by 4 spaces. A good example can be found in the previous
section. Here are some bad examples:

----------------
if ( COND() ) {
    /* Bad because the opening brace is on the same line.
}
----------------

----------------
if ( COND() )
    {
    /* Bad because the left and right braces are indented along with
    the block. */
    printf(....)
    }
----------------

----------------
/* GNU Style - fear and loathing. */
if ( COND() )
  {
    printf(....)
  }
----------------

Comments should precede the lines performing the action
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Comments should come one line before the line that they explain:

----------------
/* Check if it can be moved to something on the same stack */
for(dc=0;dc<c-1;dc++)
{
    .
    .
    .
}
----------------

+TODO: Fill in+

One line clauses should be avoided
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One should avoid one-line clauses inside the clauses of +if+, +else+,
+elsif+, +while+, etc. Instead one should wrap the single statements inside
blocks. This is to avoid common errors with extraneous semicolons:

----------------
/* Bad: */
if (COND())
    printf ("%s\n", "Success!");

/* Good: */
if (COND())
{
    printf ("%s\n", "Success!");
}

/* Bad: */
while (COND())
    printf("%s\n", "I'm still running.");

/* Good: */
while (COND())
{
    printf("%s\n", "I'm still running.");
}
----------------

Identifier Naming Conventions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here are some naming conventions for identifiers:

1. Please do not use capital letters (including not +CamelCase+) - use
all lowercase letters with words separated by underscores. Remember, C is
case sensitive.

2. Note, however, that comments should be phrased in proper English, with
proper Capitalization and distinction between uppercase and lowercase
letters. So should the rest of the Freecell Solver internal and external
documentation.

3. Some commonly used abbreviations:

----------------
max - maximum
num - numbers
cols - columns
dest - destination
src - source
ds - dest stack
stack - usually the source stack
ptr - pointer
val - value
c - the card index/position within the column
befs - Best First Search (one of the types of searches used by Freecell Solver)
a_star - also refers to "befs" from historical reasons (should be converted
to "befs" in the non-external interface.)
dfs - Depth-First Search (one of the types of searches used by Freecell Solver)
----------------

Don't comment-out - use #if 0 to temporarily remove code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Code should not be commented-out using gigantic +/* ... */+ comments. Instead,
it should be out-blocked using +#if 0...#endif+.

In Perl code, one can use the following POD paradigm to remove a block of
code:

----------------
=begin Removed

Removed code here.

=end Removed

=cut
----------------

No declarations after statements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One should make sure there are no declarations after statements in the ANSI
C code. If you're using gcc, you can make sure this is the case by adding
the flags "-Wdeclaration-after-statement -Werror" to "CCFLAGS" in the makefile.
