All source files must use the CPAN module Modern::Perl and the internal library MediaWords::CommonLibs. Thus the following should be present at the beginning of the file: 

   use Modern::Perl '2012';
   use MediaWords::CommonLibs;

Simply including these modules will, among other things, enable all Perl 5.14 features, provide common and frequently used libraries such as Readonly and Data::Dumper, and ensure use strict is enabled.

The only exception is modules that are used by the plperl stored procedures. 

Any source files that do not use Modern::Perl and MediaWords::CommonLibs must have a comment explaining why these libraries are not being used.

Code Formatting 

Developers are requested to use the mediawords_reformat_code.pl script to ensure that their code follows the formatting guidelines and to prevent merge conflicts. Ideally edited files should be reformated prior to each svn check in. 

To do run mediawords_reformat_code.pl do:

./script/run_with_carton.sh ./script/mediawords_reformat_code.pl <SOURCE FILE>

e.g.

./script/run_with_carton.sh ./script/mediawords_reformat_code.pl lib/MediaWords/Crawler/Extractor.pm

mediawords_reformat_code.pl uses the Perl::Tidy module to automatically reformat the code according to a set of rules defined in the perltidy config file at script/mediawords_perltidy_config_file. This file along with the Perl Tidy documentation is considered the authoritative version of the code formating rules. Some of the rules defined in this file are use spaces instead of tabs, 125 character maximum line length, 4 character indentation, BSD/ANSI style in which braces appear on a line by themselves and code is indented inside braces.

Other Guidelines

* Comment scripts and modules - start every module / script with a comment describing what the script does, ideally in a few lines at most.

* Use a main function - put all code that the script will execute into a main() function at the bottom of the script so that we don't have to hunt through a long script to find the executing code among the function definitions. For example:

   sub main {

      my $crawler = MediaWords::Crawler::Engine->new();
      
      $crawler->crawl();
   }

   main();


* Write self commenting code - Try to write your code so that it does not need comments to be grokkable. If there's a big block of code that needs explanation, break out discrete blocks into their own, clearly named, functions that tell the story of what the code is doing. A rule of thumb is that no single function should be longer than a single screen.

* Comment every function - Add a brief (generally one line, up to a few lines) comment before every function definition. 

Add a document describing the coding guidelines.
Add a document describing the coding guidelines.


