Commits

Shlomi Fish committed 0da8582

Add the update-HACKING-file script.

This is used to copy the HACKING file from Shlomi Fish’s homepage directory
to the one in the distribution.

Comments (0)

Files changed (3)

-XML-LibXML "Hacking"-Related Issues
-========================================
+Coding Style and Conventions for Shlomi Fish’s Projects
+=======================================================
 Shlomi Fish <shlomif@cpan.org>
-:Date: 2009-08-14
-:Revision: $Id: HACKING.txt 3943 2011-06-29 10:04:01Z shlomif $
+:Date: 2012-05-14
+:Revision: $Id$
 
 Perl Style Guidelines
 ---------------------
 Avoid until and unless
 ~~~~~~~~~~~~~~~~~~~~~~
 
-"until" and "unless" should be spelled using "if !" or "while !".
+"until" and "unless" should be spelled using "if !" or "while !" or
+alternatively "if not" or "while not".
+
+Make sure you update the "MANIFEST" file with any new source files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All the new source files should be places in the "MANIFEST" file in the core
+distribution. Note that I am considering to make use of "MANIFEST.SKIP"
+instead, which would not necessitate that in general.
+
+Make sure to update the "Changes" (or equivalently named) file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A patch should also patch the "Changes" file (whose name may vary) with the
+explanation of the change. A Changes file should not be automatically
+generated. Note that due to historical reasons, the exact format of the Changes
+varies between different projects of mine and you should try to emulate the
+style and format of the one of the CPAN distribution in question.
+
+Test programs should not connect to Internet resources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As a general rule, test programs should not connect to Internet resources
+(such as global web-sites) using LWP or WWW::Mechanize or whatever, and
+should rely only on local resources. The reasons for that are that relying
+on such Internet resources:
+
+* May fail if the machine does not have a fully open Internet connection.
+
+* Will add load to the hosts in question.
+
+* Such Internet resources can fluctuate in their content and behaviour,
+which may break the tests.
 
 Other elements to avoid
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-See http://perl-begin.org/tutorials/bad-elements/
+See http://perl-begin.org/tutorials/bad-elements/ .
 
 C Style Guidelines
 ------------------
 
 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.
+letters. So should the rest of the 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)
+iter - iterator
+idx - index
+i, j - indexes
 ----------------
 
 Don't comment-out - use #if 0 to temporarily remove code
 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.
+
+Bad:
+
+----------------
+int my_func(int arg)
+{
+    int var;
+
+    printf("%s\n", "Foo");
+
+    /* Declaration after statement. */
+    int other_var = var;
+
+    return;
+}
+----------------
+
+Better:
+
+----------------
+int my_func(int arg)
+{
+    int var;
+    int other_var;
+
+    printf("%s\n", "Foo");
+
+    other_var = var;
+
+    return;
+}
+----------------
+
+Comments should have an empty space after the comment leader
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Comments in Perl, C, Python, Ruby, and other languages should have an
+empty space after the comment leader.
+
+Bad:
+
+----------------
+#Print a value.
+print "Hello\n";
+/*Print a value.*/
+printf("%s\n", "Hello");
+----------------
+
+Better:
+
+----------------
+# Print a value.
+print "Hello\n";
+/* Print a value. */
+printf("%s\n", "Hello");
+----------------
+
+sizeof(var) is preferable to sizeof(mytype_t)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Given the choice between +sizeof(var)+ as well as +sizeof(*var)+
+and +sizeof(mytype_t)+ where +mytype_t+ is a type, the former should be
+prfereable. This way, if the type of the variable changes, one does not
+need to fix the +sizeof(…)+.
+
+sizeof() must always be enclosed in parentheses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Do not write +sizeof int+, +sizeof mystruct_t+ etc. Instead write
++sizeof(int)+, +sizeof(mystruct_t)+ .
+
+Types should end in “_t” ; Raw struct definitions in “_struct”
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+New typedefs should call their types in names that end with a “_t”:
+
+----------------
+typedef int myint_t;
+typedef struct
+{
+    .
+    .
+    .
+} mystruct_t
+----------------
+
+Prefer doing +typedef struct { ... } mystruct_t+ to declaring a struct
+separately. If a struct declartion is still needed (e.g: if it contains
+a pointer to itself) it should:
+
+1. Have an identifier that ends with “_struct”.
+
+2. Be typedefed into a type (that ends with “_t”):
++typedef struct my_struct_struct my_struct_t;+.
 scripts/bump-version-number.pl
 scripts/fast-eumm.pl
 scripts/prints-to-comments.pl
+scripts/update-HACKING-file.bash
 scripts/Test.pm-to-Test-More.pl
 t/01basic.t
 t/02parse.t

scripts/update-HACKING-file.bash

+#!/bin/bash
+cp -f /home/shlomif/Docs/homepage/homepage/trunk/t2/open-source/resources/how-to-contribute-to-my-projects/HACKING.txt ./HACKING.txt
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.