* Coding standards for XMLTV

Mostly the coding standards are: follow the existing convention.
There is code written by a variety of authors and since it is mostly
self-contained scripts there wasn't any great effort to enforce a
uniform style.  So if you are changing a file just conform to the
style that's already there.

New code should use the preferred style for the language in which it
is written.  In C use the style given by K&R (second edition), in C++
imitate the examples in 'The C++ Programming Language' (third
edition), in Java copy Sun's coding style and in Perl read the
perlstyle(1) manual page.  (This doesn't 100% match my own
preferences, but I think it is a good basis for a common standard
among several contributors.)

For grabbing listings from websites you need to write very defensively
and handle every possible condition.  For example,

    if ($role eq 'actor') {
        # handle actor
    }
    elsif ($role eq 'director') {
        # handle director
    }
    else {
        warn "unknown role $role";
    }

Even if the third case has never happened, you should detect it and
warn about it.  The format of a website will undergo small and
not-so-small changes without warning.

Another way of phrasing this principle is *do not throw away any
information*.  In the worst case you should print data that isn't
understood to stderr so that the user sees it; nothing should be
thrown away.  (Okay so you will have to strip away lots of banner ads,
navigation bars and other cruft from typical pages - but in the
listings themselves try to do something meaningful with every last
character.)

A useful technique is to store details in a hash and then when
handling the hash to make a copy and delete keys from it.  At the end,
if there are any keys left, there's something you didn't handle.

    my %h = %in; # make a copy
    if (defined(my $val = delete $p{stop})) {
        # handle 'stop' attribute
    }
    if (defined(my $val = delete $p{post})) {
        # handle 'post' attribute
    }
    # I think that's all, just check...
    foreach (keys %h) {
        warn "unknown key in hash: $_";
    }

Most of this file remains to be written, until then follow the general
advice above.

* git log messages

For the XMLTV changelog messages, I have been using the style of
describing what I did in the past simple tense: for example,

'Added a flag to stop excessive grunking when fully formed pompoms are
 not available.'

as opposed to

'Add a flag...'

For consistency, I think we should keep the same style.  So please when
committing to git write meaningful log messages and describe what you
did and why, in the past tense.

For small changes you can describe the new program behaviour, and for
this use the present tense:

'Read the whole file first before checking for markers.'

In other words, use the present tense to describe what the program now
_does_; use the past tense to describe what you just _did_.

* Subroutines (and functions, and methods)

All subroutines should have a comment at the top saying _what_ the
routine does and how to call it.  Mostly it will suffice to describe
the meaning of the different parameters and the return value.

If you want to describe _how_ a subroutine works, do so with comments
inside the subroutine body.

Using documentation systems (such as Perldoc and Javadoc) is necessary
if you're building a library which can be installed by itself, but
otherwise it's not strictly required.  Having said that, we probably
should be using Perldoc more than we are currently.

* DTD

Additions to the DTD are mainly based on three criteria:

- does a listings source being scraped include this data?
- is it something you'd expect to find in printed TV listings?
- does any application need it?

The more of these are true, the more likely something is to go in.