StyleGuide

From W3C Wiki
Revision as of 11:11, 28 April 2007 by TerjeBless (Talk)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Coding Standards

Perltidy configuration for check

`-sbt=2 -bt=2 -pt=2 -ce -l=78 -i=2 -msc=1 -nwrs=".." -nwls=".."`

Not quite, but close... Need to find an "optimal" setting and apply it.

Perltidy should probably be used as a lint and the suggested changes applied selectively. Perl is in general too complex to be automatically formatted.

Indentation

  • Two spaces per TAB, and no hard TABs.
  • Blocks and braces align K&R style.
  • Use aligning agressively; including for datastructures and other delimited things.
  • Functions with long or complex argument lists can be aligned like a block.
&function(
    $long, $arg, $list
);


operands

  • Use and, and or when appropriate; && and || only when you need higher precedence.
  • Use single quotes ' by default, use double quotes " only when you intend for interpolation.
  • Use not unless you really really mean !.
  • In boolean comparisons, prefer the TRUE and FALSE constants over shortcut booleans.
    • This is to allow for future changes when simple variables are replaced with objects and overloading of the comparison operators.
  • Don't use $var = $var . 'string' if $var .= 'string' will do.

Random Uncategorized Draft Notes

  • Give modules an an explicit version number in use Module n.m; only if we absolutely need a specific minimum version of that module.
  • Give modules an empty import list use Module qw(); to prevent namespace pollution.
  • For random values to compare against, use constant FOO => 'bar'; instead of spreading hard coded values throughout if()s in the code or declaring a whole lot of global variables.
  • Gratuitous reuse of CPAN code through modules is good; don't be afraid of extra dependencies.
    • Be prepared to help patch or maintain those CPAN modules if we need it though.
    • Balance this against what we know to be available on common Linux distros and ActiveState PPM repos.
      • Last two Fedora Core is probably a good indication of what our target should be.
  • Comment each function and most blocks.
  • Don't be afraid of whitespace; between blocks and in comments etc.
  • No arbitrary limits if they can be avoided.
    • If you set a limit (whatever it is) make sure you trap it and give a friendly error message.
    • Assumption is the mother of all fuckups. HTTP doesn't have to live on port 80; or any other fixed port you've ever dreamed of.
  • Logical blocks of code get major headings like
###############################################################################
#### Block Title. #############################################################
###############################################################################
  • Major headings get 3 blank lines of leading whitespace.
  • Minor headings (e.g. a sub with its comment) get 2 lines of leading whitespace.
  • Normal, non-inline, comments and their code get 1 line of leading whitespace.