GenDBWiki/DeveloperDocumentation/DocumentationGuidelines

GenDB Source Code Guidelines

Below you can find some guidelines and suggestions for writing you own source code within the GenDB system and for documenting the methods that you have written.

Writing new GenDB source code

If you are implementing new cool stuff within the GenDB CORE, WEB, or GUI component you should always ask yourself if you are writing a specific method in the right place. As an example, if you are implementing some functionality that could not only be used within the GUI but also in the web interface you should store that stuff only once in a backend module of the CORE component. Before you commit any changes you should of course update your CVS tree to the latest stage, test the new functionality and check everything carefully. Larger modifications should always be announced to the GenDB developer mailing list. If you have made changes in several modules please ensure that you commit all parts that are affected. If you encouter conflicts - try to resolve them. For more complex tasks it is also a good idea to have a little script that tests and checks this funtionality; we are currently looking for a way to incorporate a unit test system into GenDB.

Writing inline POD documentation

For the documentation of all classes and their methods we are using inline POD documentation that can be translated into various other formats. Usually a complete module or class documentation contains the following sections:

• NAME -- the name of the current module or class
• SYNOPSIS -- a piece of source code showing a default example (not always necessary)
• DESCRIPTION -- detailed description of the current module or class
  • Available methods -- all API methods (see below); if you have a lot of methods you should group them into specific subsections
• SEE ALSO -- references to other modules or links to further information

Thus a typical module header might look like this:

=head1 NAME

GENDB::DB_Server::Region::CDS

=head1 DESCRIPTION

Server side extensions to class L<GENDB::DB::Region::CDS>.

=head2 Additional methods

=over 4

=cut

use strict;
use warnings;

... more includes ...

... maybe some constant definitions ...


our ($VERSION) = ('$Revision: 1.40 $ ' =~ /([d.]+)/g);
1;

Especially all methods useful for other programmers should be documented carefully.

Please DO NOT write the documentation of ALL methods at the beginning of a module. Instead, you should add the POD documentation right in front of each single method as shown below:

=item * STRING B<stop_codon>()

Get the stop codon of a CDS region.

  RETURNS: string containing the stop codon of a CDS region

=cut

sub stop_codon {
    my ($self) = @_;

    return substr($self->sequence, -3, 3);
}



=item * STRING B<aasequence>()

Get the amino acid sequence of the translated CDS. The AA sequence does not include the stop codon.

  RETURN: the corresponding amino acid sequence of a CDS region as a string

=cut

sub aasequence {
    my ($self) = @_;

    my $aaseq = ...;

    return $aaseq;
} 

If a method has a number of arguments (parameters) each of them should be documented in detail as well:

=item * STRING B<sequence>(from, to)

Get the DNA sequence of a region. A subsequence may be specified by from and to values (based on indexing starting with 1).

  from: optional integer value specifying a start position for sequence retrieval
  to: optional integer value specifying a stop position for sequence retrieval
  RETURNS: corresponding DNA sequence as string

=cut

sub sequence {
    my ($self, $from, $to) = @_;

    my $sequence = ...;

    return $sequence;
}

For optimized visualization of the POD output you should always add a newline before all arguments are described and you should also describe the RETURN value(s) if any.

Please DO NOT write POD documentation for internal methods that are only used (e.g. as helper functions) within a module. These methods should be implemented at the bottom of a module and all internal method names should start with '_'. You should of course document them by normal Perl comments (starting with '#').

###
# Internal methods that are not part of the 'visible' API
###


#
# Hooks into the pre-delete chain and removes all sub regions, observations
# and annotations associated to this region from the database
#
sub pre_delete_hook {
    my ($self) = @_;
    
    # delete all sub regions first
    ...

    return;
}

At the end of most modules you will often find references to other modules as show below:

=back

=head1 SEE ALSO

L<GENDB::DB::Region>

L<GENDB::DB_Server::Region.pm>

Some suggestions for pretty sources

Here are some DOs and DON'Ts for writing source code within the GenDB system:

DO	DON'T
($abc)	( $abc )
if ($test) {	if( $test ){
unless ($test)	unless($test)
while (...) {	while(...){
my (...)	my(...)
) {	){
$a->$b	$a -> $b