Coding Style and Conventions for Shlomi Fish’s Projects ======================================================= Shlomi Fish :Date: 2012-05-14 :Revision: $Id$ 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 !" 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/ . 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