MimerDesk Coding Guidelines

Teemu Arina <teemu@ionstream.fi>

v0.2, 10 September 2001


This document describes the MimerDesk coding guidelines: How to write code that is correctly formatted and follows all of the required guidelines.

1. Code Layout

There are some general guidelines for formatting that will make your programs easier to read, understand, and maintain for other MimerDesk developers. If we all follow the same formatting guidelines it is easier to start reading code written for MimerDesk.

if ($user eq 'sysadmin')
{
    # do stuff
}

$configuration = 'mimerdesk.cfg';
$formatting    = 1;
$debug         = undef;

if    ($debug)      {debug();}
elsif ($formatting) {format();}
else                {exit;}

# Messages
sub reply_message;
sub delete_message;
sub edit_message;
sub add_message;

# Forums
sub add_forum;
sub edit_forum
sub remove_forum;

#""""""""""""""""""""#
# Example subroutine #
#____________________#

# 1. Read files from the directory
# 2. If the current filename starts with a (.)..
#    2.1 Skip file
# 3. Print filenames

2. Coding issues

# Wrong
$ref->{hashkey}
# Ok
$ref->{'hashkey'}
# Another example where quotes are not necessary
%hash = (
              SECOND => 1,
              MINUTE => 2,
              HOUR   => 3,
        );

3. Security issues

4. Using other programming languages than Perl

4.1 Using other programming languages for creating MimerDesk applications

Although in theory it is possible to use almost any programming language for MimerDesk modules and programs, we suggest using Perl for code that is included in the final release. All programs written in another language will be treated as third-party programs.

There are several reasons for this. First, it is difficult to maintain multiple versions of the library in many programming languages. Second, in order to fully take advantage of persistent database connections and other efficiency boosting features of mod_perl, all of the programs have to be written in Perl. It will be faster. Using C for structures that need speed (e.g parsers) is however acceptable. Third, MimerDesk will be more difficult to install and maintain if there are several programming languages used.

4.2 Using Java-applets and other client side browser-based technology

Java-applets are welcome if there is a good reason for them

Since java-applets make the GUI a lot slower due to the client side loading, there should be a really good reason for using them!
. Good reasons are video conferencing, games, interactive programs etc. where Java is simply the best alternative.

Flash applications should offer additional features, not features that are absolutely necessary. Flash is good for tours, music players, multimedia presentations and maybe for games and such. Other browser plug-ins should be used only for material viewing (e.g. PDF).

4.3 Javascript and DHTML

Javascript is welcome but it should not be used too heavily. Only for layout issues and GUI functionality (mouse over images, form verification etc.). If you write Javascript, make sure it works with all of the commonly used browsers (Konqueror, Mozilla, Netscape 4.x or higher, IE 4 or higher and Opera).

4.4 HTML

HTML code should be 4.01 Transitional compliant and it should look mostly the same with all of the commonly used browsers. Make it as standard as possible.

4.5 CSS

CSS is good but the same rule applies here as it applied for HTML: it should look mostly the same with all of the commonly used browsers. CSS should be CSS Version 2 standard compliant. There is a MimerDesk wide style-sheet in the files directory. Add your CSS there if possible instead of adding CSS code directly to the template files.

5. Recommended reading