Writing a YaWPS module

The most important thing is to run your programs under the -Tw flag at all times. You should also always run under use strict or know the reason why not. The use diagnostics pragmas may also prove useful.
Here are some general guidelines regarding aesthetics of code layout:

  • Tab indent.
  • Opening curly on same line after keyword, if possible, otherwise the line after.
  • One-line BLOCK may be put on one line, including curlies.
  • No space before the semicolon.
  • Semicolon omitted in "short" one-line BLOCK.
  • Space around most operators.
  • Space around a "complex" subscript (inside brackets).
  • Blank lines between chunks that do different things.
  • Space after each comma.
  • Long lines broken after an operator (except "and" and "or").
  • Space after last parenthesis matching on current line.
  • Line up corresponding items vertically.
  • Omit redundant punctuation as long as clarity doesn't suffer.

Designing your API

Write simple routines to do simple things

It's better to have numerous simple routines than a few monolithic ones. If your routine changes its behaviour significantly based on its arguments, it's a sign that you should have two (or more) separate routines.

Naming conventions

Your naming should be consistent. Function and method names should all be lowercased, longer words should be sperated by underscores (i.e. $my_variable_name, my_new_function()).

Module template

A typical YaWPS module shoud consist of at least two files. The index.cgi and admin.cgi. The index.cgi should look like the following template:
1: #!/usr/bin/perl -Tw
2: $| = 1;
3:
4: # Load necessary modules.
5: use strict;
6:
7: BEGIN
8: {
9: use lib '../..';
10: require "yawpsrc.pl";
11: use vars qw(
12: $VERSION @ISA @EXPORT
13: %cfg %usr %err %msg %btn %nav %inf %hlp %months %week_days
14: );
15: push(@INC, $cfg{scriptdir});
16: use yawps;
17: }
18:
19: # Get the form input and assign the variables.
20: my $query = new CGI;
21: my $op = $query->param('op') || '';
22:
23: # User authentication.
24: my %user_data = authenticate();
25:
26: # Define possible user actions.
27: my %user_action = (
28: my_function2 => \&my_function2,
29: my_function3 => \&my_function3,
30: my_function4 => \&my_function4
31: );
32:
33: # Depending on user action, decide what to do.
34: if ($user_action{$op}) { $user_action{$op}->(); }
35: else { my_function(); }
36:
37: # ---------------------------------------------------------------------
38: # Description here.
39: # ---------------------------------------------------------------------
40: sub my_function
41: {
42: ...
43: }

Strictness and warnings

Your module should run successfully under the strict pragma and should run without generating any warnings. Your module should also handle taint-checking where appropriate, though this can cause difficulties in many cases.

Error handling and messages

Don't let your module die/exit the perl process if possible. Use the YaWPS internal error functions to display any faults.

Documentation

Provide a README file and perhaps also release notes, changelog, etc. Provide links to further information (URL, email)

Release the module

If you're going to relase your module, please post this in the YaWPS developer forums and on the yawps-announce mailing list.
You should of course create a tarball of your distribution. Make sure tarballs always unpack into a single new directory:
tar -czvf foobar-$(VERS).tar.gz foobar-$(VERS)