This shows you the differences between two versions of the page.
Next revision | Previous revisionNext revisionBoth sides next revision | ||
developersguide [2007/01/24 09:32] – manni | developersguide [2008/02/09 18:09] – Links to tools changed to devel:tools1 manni | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== POPFile Developer' | ====== POPFile Developer' | ||
- | === 1. How do I become a POPFile developer? === | + | ==== 1. How do I become a POPFile developer? |
If you are interested in developing code for POPFile then you came to the | If you are interested in developing code for POPFile then you came to the | ||
Line 7: | Line 7: | ||
understand it. | understand it. | ||
- | Then go to the [Bleeding Edge - Source Code] [[http:// | + | Then go to the [[http:// |
- | some code and making a suggestion. | + | |
- | This is very important because you don't want to waste your time coding | + | |
- | something that someone else is working on. It's also a good idea to find | + | |
- | out whether I think your idea is good otherwise you might end up coding | + | |
- | something that gets rejected, but most likely you'll get encouragement and | + | |
- | suggestions from other POPFile developers and a "show me" response from me. | + | |
- | It is important to realize that one thing I really care about in the code | + | It is important to realize that one thing I really care about in the code base is the quality of the code itself. |
- | base is the quality of the code itself. | + | |
- | understand the POPFile coding style and how to write POPFile tests is very | + | |
- | important. | + | |
- | style will be rejected. | + | |
You will also need to sign a POPFile License Agreement, see below. | You will also need to sign a POPFile License Agreement, see below. | ||
+ | ==== 2. How do I post a patch? ==== | ||
- | === 2. How do I post a patch? === | + | First read this entire document, then create |
- | First read this entire document, then create a patch using [[:tools | diff3]] (or a | + | Before you post your patch it's a good idea if you run the POPFile test suite against |
- | similar program) and post it to the [[http:// | + | |
- | Before you post your patch it's a good idea if you run the POPFile test | + | ==== 3. How do I get CVS commit |
- | suite against your version of the code to make sure you didn't break | + | |
- | anything else. | + | |
- | tests and passes the full POPFile test suite is the best way to get on my | + | |
- | good side, get your code in CVS and one day maybe get CVS access | + | |
- | yourself. | + | |
+ | Contact the project owner, John Graham-Cumming, | ||
- | === 3. How do I get CVS commit access? === | + | ==== 4. Does POPFile have a coding style? |
- | + | ||
- | Contact the project owner, John Graham-Cumming, | + | |
- | [Bleeding Edge - Source Code] forum, follow the coding guidelines, write good tests and, even better, take direction from me on changes that I want to change in POPFile. | + | |
- | + | ||
- | + | ||
- | === 4. Does POPFile have a coding style? === | + | |
Yes, and here it is (note that not all of the POPFile source code matches this coding style... yet... if you see something that needs cleaning up then clean it up!). | Yes, and here it is (note that not all of the POPFile source code matches this coding style... yet... if you see something that needs cleaning up then clean it up!). | ||
Line 49: | Line 29: | ||
POPFile has a coding style so that all the code looks consistent and to make it easy for others to read and understand. | POPFile has a coding style so that all the code looks consistent and to make it easy for others to read and understand. | ||
- | --- Don't obfuscate your Perl. Perl is a great language for writing cross | + | * Don't obfuscate your Perl. Perl is a great language for writing cross platform code, but it is easy to be obscure and there' |
- | platform code, but it is easy to be obscure and there' | + | minimize your use of implicit variables and imagine that a new Perl programmer is trying to decipher what you have written. |
- | minimize your use of implicit variables and imagine that a new Perl | + | |
- | programmer is trying to decipher what you have written. | + | |
- | + | ||
- | --- No TAB characters in files, and use 4 space indentation. | + | |
- | return characters in files. | + | |
- | + | ||
- | --- { goes at the beginning of a new line after a sub declaration but at the | + | |
- | end of the line in all other cases. | + | |
- | + | ||
- | < | + | |
sub foo | sub foo | ||
{ | { | ||
Line 69: | Line 41: | ||
</ | </ | ||
- | --- Leave blank lines above and below blocks of comments, even when the | + | * Leave blank lines above and below blocks of comments, even when the comments are small. |
- | comments are small. | + | |
- | < | + | # Check whether the elephant feeding module is loaded and load it |
- | - Check whether the elephant feeding module is loaded and load it | + | # if necessary |
- | | + | |
if ( $efm-> | if ( $efm-> | ||
</ | </ | ||
- | --- Every module or file must have a file header that states the name of | + | * Every module or file must have a file header that states the name of the code and the purpose of the code in the file and the standard copyright notice as follows: < |
- | the code and the purpose of the code in the file and the standard copyright | + | #--------------------------------------------------------------------------- |
- | notice as follows: | + | # |
- | + | # Module.pm --- A module that handles the loading of banana wumpus drivers | |
- | < | + | # and links them into the octopus subsystem using dinolinking |
- | ---------------------------------------------------------------------------- | + | # |
- | - | + | # Copyright (c) 2001-2003 John Graham-Cumming |
- | | + | # |
- | | + | #--------------------------------------------------------------------------- |
- | - | + | |
- | | + | |
- | - | + | |
- | ---------------------------------------------------------------------------- | + | |
</ | </ | ||
- | --- Every subroutine must have a header of the following form: | + | * Every subroutine must have a header of the following form: < |
- | + | #--------------------------------------------------------------------------- | |
- | < | + | # |
- | ---------------------------------------------------------------------------- | + | # update_word |
- | - | + | # |
- | | + | # Updates the word frequency for a word |
- | - | + | # |
- | | + | # $word The word that is being updated |
- | - | + | # $encoded |
- | | + | # $before |
- | | + | # line |
- | | + | # $after |
- | | + | # line |
- | | + | # $prefix |
- | | + | # the special identification of values found in for example |
- | | + | # the subject line |
- | | + | # |
- | | + | #--------------------------------------------------------------------------- |
- | - | + | |
- | ---------------------------------------------------------------------------- | + | |
</ | </ | ||
- | --- Explain any code where the operation is not obvious with a comment. | + | * Explain any code where the operation is not obvious with a comment. The bar for not obvious should be very low, but never write something like: < |
- | The bar for not obvious should be very low, but never write something like: | + | # Increment i |
- | + | ||
- | < | + | |
- | | + | |
$i += 1; | $i += 1; | ||
- | </ | + | </ |
- | + | # This is the A PIECE OF PLATFORM SPECIFIC CODE and all it does is force | |
- | but a good comment would be: | + | # Windows users to have v5.8.0 because that's the version with good fork() |
- | + | # support everyone else can use whatever they want. This is probably only | |
- | < | + | # temporary because at some point I am going to force 5.8.0 for everyone |
- | | + | # because of the better Unicode support |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
my $on_windows = 0; | my $on_windows = 0; | ||
if ( $^O eq ' | if ( $^O eq ' | ||
- | < | + | |
- | | + | $on_windows = 1; |
} | } | ||
</ | </ | ||
- | --- Use parens instead of relying on precendence rules. | + | * Use parens instead of relying on precendence rules. |
- | + | ||
- | < | + | |
if ( ( $foo == $bar ) && ( $number > 0 ) ) { | if ( ( $foo == $bar ) && ( $number > 0 ) ) { | ||
- | </ | + | </ |
- | + | ||
- | instead of | + | |
- | + | ||
- | < | + | |
if ( $foo == $bar && $number > 0 ) { | if ( $foo == $bar && $number > 0 ) { | ||
</ | </ | ||
- | --- Don't use elsif. | + | * Don't use elsif. |
- | --- Use lowercase with underscore between words for subroutine and variable | + | * Use lowercase with underscore between words for subroutine and variable names, e.g. < |
- | names, e.g. < | + | |
+ | ==== 5. How is POPFile tested? ==== | ||
- | === 5. How is POPFile | + | POPFile |
- | POPFile has an automatic test suite that is run using the tests.pl | + | tests.pl |
- | You can type make test in the engine directory | + | |
- | run tests.pl yourself. | + | |
- | tests.pl | + | tests.pl |
- | loads them as Perl scripts. Each .tst module uses two helper functions in | + | |
- | test_assert( $test ) and test_assert_equal( $test, $expected ). test_assert | + | |
- | is used to assert that a particular test (an arbitrary piece of Perl that | + | |
- | the test_assert subroutine will eval) is true, test_assert_equal is a | + | |
- | glorified string | + | |
- | that the result of some test (test_assert_equal does no eval the $test | + | |
- | parameter) is equal to some expected value. | + | |
- | tests.pl will run all the .tst files printing a . for each test that passes | + | Each Perl module in POPFile should have a corresponding test file in the tests/ subdirectory. For example, for MailParse.pm we have TestMailParse.tst. |
- | and an appropriate error for those that fail, and then print out a summary | + | |
- | at the end of the total number of tests and the number that failed. | + | |
- | Each Perl module | + | Before checking |
- | tests/ subdirectory. | + | |
- | TestMailParse.tst. | + | |
- | Before checking in new code or submitting a patch run the test suite to | + | ==== 6. Why do I have to sign copyright over to John Graham-Cumming? |
- | protect against regressions. | + | |
+ | POPFile is released under the General Public License used for free software but in order to ensure that the actual code is free of any claims by people who's interests are different from the GPL and to enable me to litigate cleanly if someone were to break the GPL and to create derivative versions of POPFile from code that is contributed without legal problems contributors are required to sign the [[: | ||
- | === 6. Why do I have to sign copyright over to John Graham-Cumming? | + | A simple summary of this license is "you tell me that the code you wrote doesn' |
- | POPFile is released under the General Public License used for free software | + | Some background reading on the subject |
- | but in order to ensure that the actual code is free of any claims by people | + | |
- | who's interests are different from the GPL and to enable me to litigate | + | |
- | cleanly if someone were to break the GPL and to create derivative versions | + | |
- | of POPFile from code that is contributed without legal problems contributors | + | |
- | are required to sign the [[: | + | |
- | A simple summary of this license is "you tell me that the code you wrote | + | - My original thread on POPFile and code copyright: http:// |
- | doesn' | + | |
- | it in the context of POPFile, and I protect you from getting sued if your | + | |
- | code in POPFile ' | + | |
- | + | ||
- | Some background reading on the subject of copyright and copyleft and the | + | |
- | POPFile License Agreement can be found here: | + | |
- | + | ||
- | 1. My original thread on POPFile and code copyright | + | |
- | < | + | |
- | | + | |
- | 2. The Free Software Foundation' | + | |
- | < | + | |
| | ||
A very important section reads: | A very important section reads: | ||
Line 225: | Line 147: | ||
I URGE YOU TO READ THE ENTIRE FAQ.</ | I URGE YOU TO READ THE ENTIRE FAQ.</ | ||
- | + | - The Free Software Foundation' | |
- | 3. The Free Software Foundation' | + | |
- | < | + | |
"By Professor Eben Moglen, Columbia University Law School | "By Professor Eben Moglen, Columbia University Law School | ||
Line 247: | Line 167: | ||
the programmer' | the programmer' | ||
| | ||
- | | + | |
+ | </ | ||
Should you find anything in the documentation that is incomplete, unclear, outdated or just plain wrong, please let us know and leave a note in the Documentation Forum.