Commits

Shlomi Fish committed a9b21f9

Add the file HACKING.txt for style guidelines.

It's written using AsciiDoc.

Comments (0)

Files changed (2)

+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.
+
+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
+----------------
+
+Perl
 LibXML.pod
 LibXML.xs
 LICENSE
+HACKING.txt
 Makefile.PL
 MANIFEST
 perl-libxml-mm.c
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.