[Koha-devel] Koha, Style, and Perltidy

[Mike Hansen]

Hello everyone,

        It has been suggested a number of times before that we come up with a
standard style for Koha scripts in order to make the scripts easier to
read.  One such way of doing this is using a program called perltidy to
go through and format things in a certain style.  Perltidy can read its
configuration from a seperate file, which would allow us to maintain
consistency within the codebase.
        Now, there are a number of options that we should decide on before we
can effectively use perltidy.  I will present some of the major options
here along with their alternatives and some sample pieces of code
formatted with the various options.

1.  Line length:  This setting will prevent lines of code from exceeding
a maximum number of characters.  The default length is 80 columns.  Do
we want it do be more or less or the same?

2. Indentation:  There are a number of ways that perltidy handles
indentation.  First, you can specify a number of spaces to ident code
blocks.  Shown below is the indentation set to 4 spaces:
    if ( $flag eq "a" ) {
        $anchor = $header;
    }
We can change this value to anything we would like.  We can also set it
to use tabs instead of spaces to indent.

3.  Opening Brace Right or Left:  This setting controls where the
opening brace for code blocks go.  Below is an exmaple with them on the
right:
    if ( $flag eq "h" ) {
        $headers = 0;
    }
and on the left:
    if ( $flag eq "h" )
    {
        $headers = 0;
    }
Which one of these should we use?

4:  Cuddled Else:  The cuddled else style is shown below:
    if ( $flag eq "h" ) {
        $headers = 0;
    } elsif ( $flag eq "f" ) {
        $sectiontype = 3;
    } else {
        print "invalid option: " . substr( $arg, $i, 1 ) . "\n";
        dohelp();
    }
while the non-cuddled else is:
    if ( $flag eq "h" ) {
        $headers = 0;
    }  
    elsif ( $flag eq "f" ) {
        $sectiontype = 3;
    } 
    else {    
        print "invalid option: " . substr( $arg, $i, 1 ) . "\n";
        dohelp();
    }
Which one is preferable.

5.  Horizontal Tightness:  This controls the spacing for items in
"containers."  Here are the various options:
 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) {  # -pt=0
 if ( ( my $len_tab = length($tabstr) ) > 0 ) {    # -pt=1 (default)
 if ((my $len_tab = length($tabstr)) > 0) {        # -pt=2
Note that that was for parentheses.  There are similar options for
square brackets, curcly braces, and code block curly braces.

Those are a few of the major ones; however, there are more options at
http://perltidy.sourceforge.net/stylekey.html.  If you can think of
anything else that would be beneficial style-wise, let me know.  If you
would please give me your comments and opinions (preferably along with
why you think that way would be best for Koha), I would greatly
appreciate it.  Hopefully we will be able to get a standard style for
Koha from this thread.

Thanks,
        Mike


-- 
Mike Hansen <address@hidden>