Formatting Code

See also:

• SvnRepository#RulesForCheckins
• PerlTidy
• CodingStandardsDiscussions#Formatting_Code

It is important when working with other people to make sure source code is consistently formatted. To help with this, the source code repository automatically checks that files have been consistently formatted before allowing them to be checked in. Any code belonging to the Foswiki core, or any of the extensions shipped by default with the core, is required to be correctly formatted or the checkin will be rejected. Other extensions may be 'flagged' as requiring checking by placing a file called TIDY in the directory tree containing the sources. Similar to Apache's .htaccess, the existence of this file affects all sources in the file tree in and below the directory where it was found.

• TIDY does not exist -- check nothing (code can be formatted however you want)
• TIDY exists and is empty -- check everything - all source files must be formatted according to the standard
• TIDY exists and contains only the word OFF or contains (possibly among other things) a line: <language> OFF -- disables checking <language> files for this subtree e.g. perl OFF
• TIDY exists and contains (possibly among other things) a line such as: perl -q -l=0 -i=2 -pt=2 -nsfs -ce -novalign -- check using these formatting options instead of the standard - not recommended (please use the defaults)

If you use the BuildContrib (highly recommended) then you can use perl build.pl tidy to run all available formatters on your code.

Formatting perl code

The Foswiki standard for formatting perl source files is to run the standard perltidy command without any formatting options (ensured by the -npro option)

perltidy -npro -b <filename>.pm

Note that individual perl source files can contain special beginning and ending comment markers around code to be passed to the output without formatting. The beginning marker is #<<< and the ending marker is #>>>

Are your commits being rejected even though they're tidied? You may need to upgrade perltidy, or use the version shipped with BuildContrib. See PerlTidy#Versions.

Formatting Javascript Code

At this point in time Javascript sources are not checked. However in the future we are likely to use js-beautify for this (the engine behind http://jsbeautifier.org)

Formatting CSS

At this point in time CSS sources are not checked.