sgpemv2/doc/sgpem2dman.texi

\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename sgpem2dman.info
@settitle SGPEMv2 Developer Manual
@include vers-dman.texi
@c %**end of header

@dircategory SGPEM v2 - A Process Scheduling Simulator
@direntry
* Developers: (sgpem2dman)Top
@end direntry

@c % --------------------------------------------------

@copying 
This is SGPEMv2 Developer Manual (version @value{VERSION}, 
@value{UPDATED}).

Copyright @copyright{} 2005 University of Padova, dept. of Pure 
and Applied Mathematics

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end copying

@c % --------------------------------------------------

@titlepage
@title  SGPEMv2 Developer Manual
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Giovanni Giacobbi (@email{ggiacobb@@studenti.math.unipd.it})
@author Filippo Paparella (@email{ironpipp@@gmail.com})
@author Paolo Santi (@email{psanti@@studenti.math.unipd.it})
@author Matteo Settenvini (@email{matteo@@member.fsf.org})
@author Marco Trevisan (@email{evenjn@@gmail.com})
@author Djina Verbanac (@email{betalgez@@yahoo.com})
@author Luca Vezzaro (@email{lvezzaro@@studenti.math.unipd.it})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
  
@c Output the table of contents at the beginning.
@contents

@c % --------------------------------------------------

@c SGPEM v2 Developer Manual

@c % --------------------------------------------------

@ifnottex
@node Top, History, (none), (dir)
@top How to contribute to development
  
@insertcopying
@end ifnottex

@menu

* History::       The history of changes to this document.

* Directory overview:: How SGPEM sources are organized

* Writing documentation:: How to write formal documents
                          for draft approval

* Coding style::  Here there are the rules you should conform
                  to when working on SGPEM

* Committing changes:: Some notes on how we keep our 
                       versions organized, how to use
                       our repository, and how we would
                       like you to commit patches

* Using the Mailing List:: How to compose your messages
                           when contacting us on the ML

* License:: The full text of the license under which this
            manual is given to you

* Concept index:: Complete index

@end menu


@c % --------------------------------------------------

@node       History, Directory overview, Top, Top
@unnumbered History
@cindex history of changes

@table @strong

@item 2006, February 21st, @r{--- Djina Verbanac}
Added anomaly classes in the subsection 
anomaly solving process.

@item 2006, February 7th, @r{--- Matteo Settenvini}
Added subsection about the anomaly solving process.
Fixed C++ code conventions about how to document classes,
and the note about static non-const members in classes.

@item 2006, February 2nd, @r{--- Luca Vezzaro}
Updated coding style with a point on static non-POD
objects.

@item 2006, January 27th, @r{--- Matteo Settenvini, Djina Verbanac}
Add section about conventions to be followed when 
documenting anomalies.

@item 2006, January 27th, @r{--- Luca Vezzaro}
Added entry on initialization lists and C-style 
comments in C++ Coding Style section.

@item 2006, January 26th, @r{--- Matteo Settenvini}
Added reference subsection about documenting code. Added
decisional and communicative norms.

@item 2006, January 26th, @r{--- Djina Verbanac}
Added section about the writing of documentation

@item 2006, January 24th, @r{--- Luca Vezzaro}
Updated some code snippets whose style were
inconsistent with our coding rules. Added the point on
operator overloading to the coding conventions.

@item 2005, December 26th, @r{--- Matteo Settenvini}
Changed directory layout for @samp{src}. Added 
@samp{swe/prototypes} to repository layout.
Added one more convention about C++ header files and their
licensing.

@item 2005, December 11th @r{--- Matteo Settenvini}
Added sources' directory description and repository usage
guidelines. Included full FDL license text.

@item 2005, November 8th @r{--- Matteo Settenvini}
First draft of this document

@end table

@c % --------------------------------------------------

@node    Directory overview, Writing documentation, History, Top
@chapter Directory overview
@cindex  directory layout
@cindex  source code organization

If you need to work on SGPEM sources, you'll probably
be interested in understanding how this package directory
structure is organized.

What follows is the tree you'll find after uncompressing
the SGPEM tar archive.

@table @samp

@item config/
Files used by Autotools while configuring 
and compiling SGPEM.

@item data/
Various data SGPEM will use at runtime, like icons, 
images, XML DTDs, User Interface (@file{*.ui})
definition files, and so on.

@item doc/
Inside this directory you'll find the User and Developer 
Manuals, like the one you're reading, ready to be compiled.

@item desktop/
The desktop menu entries for FreeDesktop compliant 
Desktop Environments.

@item distro/
Files used to prepare a package for a specific platform,
maybe containing the installer data.

@item m4/
M4 macros used by Autoconf.

@item po/
Here are stored the Gettext PO catalogs. If you are a 
translator, you should first look here in order to 
localize SGPEM into your language.

@item src/
The source files of SGPEM.

@end table

@c % --------------------------------------------------

@node    Writing documentation, Coding style, Directory overview, Top
@chapter Writing documentation
@cindex  documentation

@menu 

* Formal documents and draft proposals:: How a good document is formed

* Documenting code:: Style and norms to automagically generate 
                     documentation from code

* Reporting anomalies:: When something goes wrong

@end menu

@c % ---- new section

@node    Formal documents and draft proposals, Documenting code, Writing documentation, Writing documentation
@section Formal documents and draft proposals
@cindex formal documents
@cindex draft proposals

@subsection Introduction

For writing and editing technical documents we use a subsection 
of the free (as in speech) office suite @emph{OpenOffice.org 2.0.0}, 
namely @emph{OpenOffice.org Writer}.

We sporadically also use other parts of the suite, such as 
@emph{OpenOffice.org Calc} for calculations and 
charts, and @emph{OpenOffice.org Impress} for presentations.

@subsection Technical document format
All technical documents must respect the style and formats 
explained hereafter.

@itemize
@item
@emph{All the documents start with a Cover Page} : 
The @b{cover page} contains in the right corner the logo, name and address 
of the company. In the middle of the page there's the @b{title} of the specific 
technical document. Under the title goes the @b{acronym} of the project 
(@acronym{SGPEMv2}), followed by the @b{version} of the document. 

Versions use the format @samp{x.y}, where both @samp{x} and @samp{y} 
are integers. Minor changes to the document, like grammatical and 
spelling corrections comport the increment of @samp{y}, while structural
or significant changes (for example, changing the way to resolve a 
specific problem) comport the increment of @samp{x}. 

After the version number, it comes the @b{date} of the last modification 
made to the technical document. At the end of the cover page it should
be reported the @b{status} of the document, either @emph{Formal} or 
@emph{Informal}, followed by one of the tags @emph{External} or 
@emph{Internal}.

The @b{footer} of the cover page should contain the name of the @b{Author} of 
that technical document. 

@item
The page after the cover page has to contain:

    @enumerate

    @item
    @strong{Distribution List}: to whom the document goes. It includes 
    the Surname and Name of the person to be reached by the document, 
    along with the role of that person.

    @item
    @strong{History of changes}: where to trace the changes made to the 
    document, including the date of the edit, the person who made the 
    change, and the reason(s) of it.

    @item
    @strong{List of Approved Versions}: here are traced all the approved 
    versions of the document, reporting the date and the name of the 
    person who approved that particular revision.

    @end enumerate

@item
An @b{Abstract} has to follow the List of Approved Versions: it's 
a short one-liner of what the document is about.

@item
On a new page, there's a @b{Table of Contents} that shows all 
the @b{Headings} in the file.

If the document includes a lot of figures, then after the @b{Table of
Contents} there should be an @b{Illustration Index}.

@item
After that, every document has to start with the @b{Introduction} section, 
where it will be described the purpose of the document and the purpose 
of the product, along with a list of used @b{References} to other 
documents or resources.

@item
Other parts of the document are specific to the technical document 
itself, and therefore should be managed by the editor. 
Mostly, the general structure for the more common documents can be found at
@uref{http://www.math.unipd.it/~tullio/IS-1/2005/Progetto/Documenti.html} 
(in Italian).

In the @samp{docs/misc/} directory of the Subversion repository,
there's an OpenOffice.org @b{template} with some already defined 
styles you should inherit from. Its name is @file{templatedocument.ott}.

@item
At the end of every document there should be a @b{Glossary}. The Glossary 
is a file on its own (usually, @file{docs/externals/Glossary.odt} 
off the repository), so new entries must be inserted into this latter.

Every technical document should ``include'' the afore mentioned file. 
Please refer to the @emph{OpenOffice.org} manual about @emph{Sections} to know
how to do so. The Glossary will so be linked to the current document 
dinamically, and every change done on the Glossary will reflect 
in an automatic update in every referer.

In this way all the technical documents are always able to have the 
latest up-to-date and synchronized revision of the Glossary.

@item
The @b{Header} of all pages, except the one on the cover page, 
contains:

@itemize
@item 
in the left corner, the name of the company;

@item
in the right corner, the chapter number and name.
@end itemize

@item
The @b{Footer} of every page, except on the cover page, contains:

@itemize
@item
in the left corner, the title of the document followed by the date of 
the last modification;

@item
in the right corner it contains the number of the page due to the total 
number of  pages.
@end itemize

@end itemize

To make it easier to abide these rules, please remember to inherit 
from the template document. It lays down a foundation for all 
the style guidelines mentioned above.

@c % ---- new section 

@node    Documenting code, Reporting anomalies, Formal documents and draft proposals, Writing documentation
@section Documenting code

In order to generate documentation straight from the source code:

@subsection C++ code
@cindex documenting C++ code

Please refer to @emph{Doxygen} manual 
(@uref{http://www.stack.nl/~dimitri/doxygen/manual.html}) 
in order to learn how to use this automatic tool for extracting 
documentation from code.

Every function, class, class member, class method, 
and enumeration in code should be documented, less of trivial 
static global functions visible only to the 
current compilation unit.

In particular, for functions and methods, you should use
@code{\param} and @code{\return} to describe respectively
parameters and return value.

@subsection Python code
@cindex documenting Python code

It is usually possible to annotate Python classes so that
calling the @code{__doc__} method of an object returns
its documentation string. 
Please refer to the Python manual at @uref{http://www.python.org/}
to learn more of it.

However, if we want to generate good documentation straight
from code, with the help of Doxygen, we should use the @samp{#} 
documenting style. Please look at the end of 
@uref{http://www.stack.nl/~dimitri/doxygen/docblocks.html} for 
an example.

@c % ----- new subsection

@node    Reporting anomalies, (none), Documenting code, Writing documentation
@section Reporting anomalies
@cindex  anomaly
@cindex  bug

@emph{Note}: sometimes we will refer to an anomaly with the less-formal
term ``@emph{bug}''.

Anomaly documentation is divided in two parts. The first part concerns the 
@b{Anomaly Investigation} and the second one the @b{Anomaly Resolution}. 
All informations about anomalies are held in the document named 
@file{AnomalyRecords.odt}. If you find an anomaly you should start 
a new page via a page-break, and create a header as follows:

@table @strong

@item ID
Identification number of the anomaly, a unique integer

@item Summary
A one-liner with a summary of the anomaly

@item Severity
This field describes the impact of a bug.
     
     @table @samp
     @item Blocker 	
     Blocks development and/or testing work
     @item Critical 	
     crashes, loss of data, severe memory leak
     @item Major 	
     major loss of function
     @item Minor 	
     minor loss of function, or other problem where easy workaround is present
     @item Trivial 	
     cosmetic problem like misspelled words or misaligned text
     @item Enhancement 	
     Request for enhancement
     @end table


@item Anomaly Class
This field contains the name of the class to which the anomaly belongs to.
There is no need to describe the function of this classes, because as you can see the
names are self explanatory. 

     @table @samp
     @item Extra (superfluous)
     @item Missing
     @item Ambiguous
     @item Inefficient
     @item Improvement needed
     @item Not conforming to standards
     @item Risk-prone
     not wrong but there are known, safer, alternative methods
     @item Incorrect
     @item Not implementable
     @item Safety
     @item Not adequately documented
     @end table


@item Reporter
Name and email of the person who discovered the anomaly

@item Date of Identification
Timestamp at which the anomaly was identified

@item Milestone
The milestone affected by the anomaly (e.g., m0.1)

@item Document
Document (with version number) affected by the anomaly (e.g., Tecnical Specification, 
Product Definition, code, documentation, @dots{}).

@item Status
Please choose one and only one of the following states.

These are used @strong{before} reaching a resolution:

      @table @samp

      @item UNCONFIRMED
      This bug has recently been added to the database. Nobody has validated that 
      this bug is true. The manager will usually confirm this bug, changing its state 
      to @samp{NEW}, but in case the bug existance is quite clear, any stakeholder
      can mark it as such. 

      The anomaly may be marked also @samp{RESOLVED} by the manager, if it is
      @samp{INVALID}, @samp{DUPLICATE} or so on, but @strong{not} 
      @samp{RESOLVED FIXED}.
      
      @item NEW
      This bug has recently been added to the assignee's list of bugs and must be 
      processed. Bugs in this state may be accepted, and become @samp{ASSIGNED}, 
      passed on to someone else, and remain @samp{NEW}, or it can be 
      made also @samp{RESOLVED}.

      @item ASSIGNED
      This bug is not yet resolved, but is assigned to the proper person. From here 
      bugs can be given to another person and become @samp{ASSIGNED} with a different
      assignee, or resolved and become @samp{RESOLVED}. 
      
      @item REOPENED
      This bug was once resolved, but the resolution was deemed incorrect. For example, 
      a bug is @samp{REOPENED} when more information shows up and the bug is now 
      reproducible. From here bugs are either marked @samp{ASSIGNED} or 
      @samp{RESOLVED}.

      @end table

Instead, @strong{after} a resolution, the state should change to one of:
      
      @table @samp
      
      @item RESOLVED
      A resolution has been taken, and it is awaiting verification by @acronym{QA}. 
      From here bugs are either re-opened and become @samp{REOPENED}, are marked 
      @samp{VERIFIED}, or are closed for good and marked @samp{CLOSED}.
      
      @item VERIFIED
      @acronym{QA} has looked at the bug and the resolution and agrees that the 
      appropriate resolution has been taken. Bugs remain in this state until the product 
      they were reported against actually ships, at which point they become @samp{CLOSED}.

      @item CLOSED
      The bug is considered dead, the resolution is correct. Any zombie bugs who choose 
      to walk the earth again must do so by becoming @samp{REOPENED}.

      @end table

@item Assigned to
Who's working to resolve this anomaly, name and email. Usually, it's initially left empty.

@item Description and comments
Latin creativity at work -- text describing the reasons for assuming 
the presence of an anomaly. Please be as clear as possible. Unfortunately, 
giving guidelines in this sense is quite difficult @enddots{}

As for follow-ups, always start with the name of the editor, email and the timestamp
of the comment, assigning a numerical ID to it.
An example of a comment would be:
@smallexample
@group
-- Comment #1, Slartibartfast <slarti@@go.eu>, 2006 Jan 27th - 16:13 --
Okay, I'll go and fix the time-space continuum on last Friday 17th. 
Just give me the time to put the gas in my spaceship, will you?
@end group
@end smallexample

@strong{Important}: please report it clearly in a new comment if you 
change any field of the anomaly header.

@end table

When the anomaly is resolved, a footer is added to it, with:

@table @strong
@item Date
Timestamp of the resolution date

@item Resolution
Choose one and only one of these tags. Please remember to change bug state 
accordingly and to report you've done so in a comment.

    @table @samp

    @item FIXED
    A fix for this bug is checked into the tree and tested. 

    @item INVALID
    The problem described is not a bug. 
    
    @item WONTFIX
    The problem described is a bug which will never be fixed. 

    @item DUPLICATE
    The problem is a duplicate of an existing bug. Marking a bug duplicate requires 
    the bug# of the duplicating bug and will at least put that bug number in the 
    description field. 

    @item WORKSFORME
    All attempts at reproducing this bug were futile, and reading the code produces 
    no clues as to why the described behavior would occur. If more information appears 
    later, the bug can be reopened. 

    @item MOVED
    The problem was specific to a related product whose bugs are tracked in another 
    bug database. The bug has been moved to that database.

    @end table


@item Fixed by
Usually it's the same person as the assignee.

@end table

@c % ----- new subsection

@subsection Roles solving anomalies

When solving an anomaly, we mostly follow the pattern therein explained:

@enumerate

@item
@b{Anybody}, having any role, can report an anomaly about the work done by someone else. 
It doesn't make a lot of sense reporting a bug about what you're doing: you just 
fix it and carry on.

It may be sensible to report problems about your work only if you discover them 
in a second moment, when you don't cover the same role anymore, so the assignee
would be different by the reporter.

@item
The discussion starts. Usually the verifier will check the anomaly exists, but
if enough people confirm the bug, the @b{manager} can decide to mark the bug as 
@samp{NEW} as well.

@item
Once it is clear who's the responsible for fixing the anomaly, the @b{manager}
assign the bug to them, marking it as @samp{ASSIGNED}.

@item
A fix/patch may come up from different sources, even by the reporter, 
but only the @b{assignee} can apply it to the tree and mark the bug as 
@samp{SOLVED}. They take full responsability of the fix.

@item
The @b{verifier} does the needed @acronym{QA,Quality Assurance}, and then either
reopens the bug or marks it as @samp{VERIFIED}.

@item
When and only if the product ships, a @samp{VERIFIED} anomaly may
become @samp{CLOSED}, by hand of the @b{manager}.


@end enumerate

@c % --------------------------------------------------

@node    Coding style, Committing changes, Writing documentation, Top
@chapter Coding style
@cindex  coding style

In this chapter we explore some self-imposed coding standards
we tried to follow when coding SGPEM.
If you plan to extend it in any way, you should conform to the 
guidelines explained thereafter.

@menu

* Editors ::   Some things you should know about indentation
               and editors

* Coding in C++::

@end menu

@c % --------------------------------------------------

@node    Editors, Coding in C++, Coding style, Coding style
@section Editors
@cindex  editors
@cindex  emacs

@c this needs rework, of course

IDEs are a bad choice, since usually they leave your directory
dirty, and full of temporary or project files. Please avoid their
use if not strictly necessary.

A good choice for an editor is @acronym{GNU} 
Emacs, but every other editor that both insert spaces instead of
tabulation characters and has a good Unicode support will do.

Your files should be in ``UNIX mode''; that is, only a char is used
for a newline. On DOS-based systems, usually two chars are employed:
the newline char and the carriage return one. 
Failure to check your text files are correctly saved wastes space 
and others' patience, so please take care.

This command usually fixes the problem (@emph{note}: run it as 
it is only if no binary files are present in the current directory!):
@example
for i in *; do tr -d '\r' < $i > $i.d; mv $i@{.d,@}; done
@end example

Using spaces instead of tabs in indentation is useful to ensure 
that your file will be correctly shown if another developer on another machine 
opens it with Emacs, Vim, Notepad, or what else he likes. A good 
idea is to use an editor which substitutes the @key{TAB} character 
with spaces. Most UNIX editors indent text files cleverly. The tab size is set
to 2, the Emacs default.

You may want to set @code{indent-tabs-mode} to @code{nil} in your 
@file{$HOME/.emacs} initialization file. It's an option you can find via
@key{M-x} @command{customize-group fill}.

@acronym{GNU} Emacs has another nice property: it can automatically indent
code in a whole region for you, with @kbd{M-x indent-region}. 
Moreover, if you can get accustomed to it, you can activate the
automatic indentation while in a programming mode, by
typing @kbd{C-c C-a}.
Experienced programmers find it saves quite a lot of time, but
we guess it's just a matter of taste.

@c % --------------------------------------------------

@node    Coding in C++, (none), Editors, Coding style
@section Coding in C++
@cindex  c++
@cindex  coding, style

SGPEM is mostly written in C++, an Object Oriented language
ideated by Bjarne Stroustrup and standardized in 1998 by ISO.
Here are explained some guidelines you should keep well in mind
if you want to contribute to this project.

@menu 

* C++ Coding Style::

* C++ Coding Conventions::

@end menu

@c % --------------------------------------------------

@node C++ Coding Style, C++ Coding Conventions, Coding in C++, Coding in C++
@subsection C++ Coding Style
@cindex coding style

These are some notes on coding style, and things
you should keep in mind whenever extending SGPEM
source code.
Patches to the source that don't uniform to these
guidelines are likely to be rejected and need rework.
Coding styles are highly subjective and are often the 
cause of harsh holy wars. Here we try also to give
a rationale of these choices, supporting our statements.

@enumerate
@item
Left curly braces go on a newline, respect to
the statement that comes before them. Right curly 
braces are to be put into a newline too.
It may make you feel uneasy at first, but this 
behaviour is preferable because it clearly let you
identify code blocks.
Moreover, it is observed that putting left curly
braces on the same line of a statement isn't a rule
you always follow: a lot of exceptions are raised by
particular situations, like: ``should my brace go on the
same line after a class initialization list? and after
a @code{for} loop declaration? what happens after
namespaces declaration?''
So it's best to stick to a well known practice and
put it always on a newline.
A lot of complex software projects follow this rule
because it also increases manutenibility: keep in mind 
that you aren't writing code for yourself, but for others 
to read.

@item
The return type for every function goes on a 
line, while the function name and its parameters 
go on the following, without any leading space. 
This makes easier to @command{grep}
the source. For example, if you're searching for a 
declaration of @code{int foo::bar()} inside a large
directory, grepping for: @samp{'/^foo::bar/g'} will
immediately pop out the correct result, whereas,
if you didn't follow this rule, you would have
searched for @samp{'/foo::bar/g'}, thus finding
@strong{all} recurrences of the function in the code,
even function calls.

@item
Use the following example to understand how we want
you to space expressions:
@example
@code{ type var = exp1 OP (exp2 OP fun1(exp3)); }
@end example
And for parameters, the following spacing is preferable:
@example
@code{ function(par1, par2 = value, ...)}
@end example

@item 
Please define pointers like @code{type* var} 
instead of @code{type *var}.

@item 
Labels go indented on the same level of the 
containing code block. For example:
@example
@verbatim
switch(x) 
{
case 1:
     // foo
case 2:
     // bar
default:
     // baz
}
@end verbatim
@end example
Remember that also @code{public}, @code{protected} and
@code{private} are labels.

@item
Put incomplete class declarations before their interface,
documenting it. For example:
@example 
@verbatim
/** \brief I'm a useless class
 *
 *  This class is completely useless.
 */
class C;
      // [...] 

class C 
{
public:
      // [...]
};
@end verbatim
@end example

@item
All header files of the libs and the engine
follow a common model. Try to adhere to it
by looking at existing headers. Document them 
fully, even if it is tedious, using a 
Doxygen-like syntax. The payback will be 
high, we assure you.

@item
Class names are composed of UpperCamelCase words.
Member functions are composed of 
lowercase words, separated by 
an underscore, since both the STL and Gtk-- use
this convention.
Member data are lowercase words (can be 
separated by an underscore).
Enums members are lowercase and they have 
a prefix that tells something about their 
function, e.g., in an enum named @emph{signal},
 ``@code{signal_*;}''.
Macro names are written all in capital.

@item
Private member object and function names always 
begin with an underscore. Public and protected
ones don't.

@item
Some (broken?) versions of autotools had problems with extensions
other than @samp{.cc} for C++ implementation files (e.g. 
automake didn't produce correct implicit rules for them).
Consequently, in order to avoid problems, we require you
to use the following extensions:
   @itemize

   @item
   @samp{.cc} : C++ implementation files

   @item
   @samp{.hh} : C++ header files

   @item
   @samp{.tcc} : Template implementation files

   @end itemize

You can also add to the end of your @file{~/.emacs} the line:
@example
@code{(add-to-list 'auto-mode-alist (cons "\\.tcc\\'" 'c++-mode))}
@end example
to automatically associate the @samp{.tcc} extension to
the @samp{c++-mode}.

@item
Constructor initialization list uses the following format:
@verbatim
C::C(T1 arg1, T2 arg2, ...) :
	m1(arg1), m2(arg2)...
{
   //...
}
@end verbatim

@end enumerate

@c % --------------------------------------------------

@node    C++ Coding Conventions, (none), C++ Coding Style, Coding in C++
@subsection C++ Coding Conventions
@cindex  coding conventions


Some common rules you should keep in mind when writing
new code:

@enumerate

@item
Never use @code{std::cout/cerr} if you can do 
without them.
Use @code{printf()} and @code{fprintf()} from 
@code{cstdio} instead,so that marking strings 
for @command{gettext} translation will be easier.

@item
Don't use ``@code{using}'' directives into the 
global space, even in a @samp{.cc}, and neither in other
namespaces. If you don't keep this in mind,
you're buying to everybody a (big) problem.
``@code{using}'' makes sense
at the beginning of a function to improve
code readability, and you should be specific:
@enumerate
 @item
 ``@code{using namespace std;}'' is bad
 @item
 ``@code{using std::string;}'' is good
@end enumerate

@item
When treating long template names, remember that 
@code{typedef} (along with @code{typename} as 
needed) are your best friends, expecially at
the beginning of class declarations or function
definitions.

@item
``@emph{Syscalls}'' are evil for portability. 
Thread calls can sometimes escape this rule (since
they're quite different from system to system,
and @acronym{GNU}/Linux 
ones are really good), but
remember that every UNIX/Win32/Solaris/etc.
native call you use means extra-work somewhere
in the near future.
If a portable toolkit we're using provides the
same functionality, it should be preferred to a
system call.

@item
You should start all your source files, both header
and implementation ones, with a license notice, like 
this (no leading white lines):

@smallexample
@group
// path/from/topsrcdir/file.ext - Copyright @strong{<year>}, University 
//                                of Padova, dept. of Pure and Applied 
//                                Mathematics
//
// This file is part of SGPEMv2.
//
// This is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
//
// SGPEMv2 is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with SGPEMv2; if not, write to the Free Software
// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
@end group
@end smallexample

The style you use to comment this out obviously changes with
the language you're employing.

@item
Only exportable classes and functions inside
a library should be marked with correct
visibility attribute (usually a macro we defined
as @code{SGP_DLLEXPORT}). All the others are marked with
@option{--visibility=hidden} from the compiler, and aren't
available outside the @acronym{DSO, Dynamic Shared Object} 
they live in, so that they don't clutter 
the @acronym{DSO} namespace.

@item
When you do something, remember to update the
@emph{ChangeLog}. This is essential.
More on this on @ref{Committing changes}.

@item
Remember macros for inclusion at the beginning of header
files, as well in template implementation files.
In the latter case, you may want to include the template
implementation files in the corresponding header files.
An example of a correct inclusion directive is:
@example
@verbatim
#ifndef HELLO_WORLD_HH
#define HELLO_WORLD_HH 1

// interface definitions

#endif
@end verbatim
@end example

@item
Please follow this order when declaring a class interface:
       @enumerate
       
       @item
       Incomplete declarations of nested classes and
       friend functions / classes declarations.

       @item
       Typedefs

       @item
       Enums

       @item
       Non-static member functions

       @item
       Static member functions

       @item
       Static constant data members

       @item
       Variable data members

       @end enumerate
Static non-const public data members shouldn't exist.
Nested classes go declared @strong{outside} their
containing class. For example:
@example
@verbatim
class C;

class C 
{
      class D;
      // ...
};

class C::D 
{
      // ...
};
@end verbatim
@end example
The order for visibility should be: @code{public}, then
@code{protected}, then @code{private}.

@item
Use operator overloading with care, only define
overloaded operators if the use of that operator is a 
natural way to perform a particular operation on the 
object(s).
In case operator overloading is considered the 
best choice, a lot of operators should still be avoided 
due to their profound integration with the language, 
and their tendency to lead to ugly bugs. Some
examples of these operators are: the casting operator,
@code{operator delete}, @code{operator new}, 
@code{operator ^}.

@item
The C++ standard library is your best friend. For example, 
if you need to allocate some temporary variable on the heap,
use an @code{auto_ptr<>} that does the right thing even when
an exception is raised, and that respects 
@acronym{RAII,Resource Acquisition Is Initialization}.

Also using extensively algorithms like @code{for_each} and
@code{copy} greatly helps.

@item
Use @code{glib::ustring} in place of @code{std::string} as 
often as possible, to ensure Unicode support.

@item
If you need a smart pointer, be sure to check out 
@code{glib::RefPtr<>}.

@item 
"C-style" comments are useful but are also problematic when you 
need a fast way to exclude code from execution. Since this
kind of comments cannot nest, C-style comments cannot be 
used to exclude code already commented with these old-way 
comments. For this reason there is no need to complicate our
lifes with two styles of comments, the C++ comment (//) is 
more than enough, and typing isn't a problem since most editors 
support batch-commenting for multiple lines of code.

@item
Never use global static variables of non-POD (Plain Old Data) 
type.
The reason why not doing this is fundamental, and it is well
described, along with a possible alternative here: 
@url{http://www.parashift.com/c++-faq-lite/ctors.html#faq-10.12}.

@end enumerate


@c % --------------------------------------------------

@node    Committing changes, Using the Mailing List, Coding style, Top
@chapter Committing changes
@cindex  repository
@cindex  subversion

SGPEM sources are held in a repository managed by 
Subversion. This is not an introduction on how to 
use this tool. For that, you should refer to its own 
manual, located at @url{http://svnbook.red-bean.com/}.
Rather, it sets some ``best practices'' you ought
to follow committing changes to the repository.

@menu 

* Introduction and goals::

* Repository layout::

* Basic svn usage::

* Gold rules on committing::

* How to write good log messages::

* Conflicts resolution::

@end menu


@c % --------------------------------------------------

@node    Introduction and goals, Repository layout, Committing changes, Committing changes
@section Introduction and goals
@cindex  repository
@cindex  subversion

The Subversion repository, commonly referred to just as ``repository'', 
is the place where all the material produced within this project will 
live.

There is a strong need to maintain an history of development data,
even on plain documentation, whether it is a proprietary file format 
describing an UML chart, or some lovely C source code.

Mantaining versioned files for everything makes developers more free to cut,
modify, hack, and revamp them, with the safety that older versions
can always be fetched again.

This document describes some guidelines for maintaining the 
repository as clean as possible, by defining some restrictive 
rules that developers must respect in order to avoid abusing 
of the customizability this tool offers.

@c % --------------------------------------------------

@node    Repository layout, Basic svn usage, Introduction and goals, Committing changes
@section Repository layout
@cindex  repository
@cindex  directory layout

The layout you'll find inside the repository will be:

@table @samp

@item swe/branches
This is the same as tags, except that commits are allowed inside the
branch. Please refer to common development models to decide what
should or should not be done inside a branch. Note that
branching isn't something everybody should do: it should be agreed 
together with the project administrator.

The format of a branch is:
@example
<@emph{version_number}>-r<@emph{revision_number}>--<@emph{branch_name}>
@end example

Example:
@example
1.2-r164--guirestyle
@end example
@c -- end swe/branches

@item swe/docs
(@emph{subdirectories}: @samp{internals}, @samp{externals}, 
                        @samp{manuals}, @samp{misc})

Contains all drafts intended for the developers.  This
directory doesn't support tagging and branching because drafts
has ``eternal'' life. If needs arise, they'll rather need to be 
renamed appending their version to their filename (-01, -02, etc.).
@c -- end swe/docs

@item swe/prototypes
A number of explorative prototypes we've set up to assess
availability and workingness of needed technologies.
@c -- end swe/prototypes

@item swe/tags
It contains copies of the @samp{trunk/} directory. Note that 
tagging the trunk directory reflects in a double space only 
for your local working copy, while it is a @math{O(1)} 
operation for the server. Changes and commits are NOT 
allowed here.  Please note that tagging must be agreeded 
with project administrator. 

The format of a tag is: 
@example 
<@emph{version_number}>
@end example

Example: 
@example
1.0
@end example
@c -- end swe/tags

@item swe/trunk
(@emph{subdirectories}: @samp{doc}, @samp{src}, @dots{})

This is the main development area where source files are held.
Usually, official releases spin off the trunk.
For a list of the directories layed out therein, please 
refer to @ref{Directory overview}.
@c -- end swe/trunk

@end table

@c % --------------------------------------------------

@node    Basic svn usage, Gold rules on committing, Repository layout, Committing changes
@section Basic svn usage
@cindex  repository
@cindex  svn
@cindex  locking files

In your daily use of the repository you will mostly need to know a
very small subgroup of svn commands. Other ones are usually for fine
tuning operations (like setting file binary flags, keyword expansion, managing
the repository tree, etc.), which are tasks carried out by the repository
administrator.

Here there's a quick reference about such commands:

@table @samp

@item svn checkout @emph{http://svn.thgnet.it/swe/drafts}
Downloads a copy of the current @samp{drafts/} directory contents.
Checking out the root repository dir (@samp{swe/}) may
result, in near future, to a @strong{big} download, as
branch and tags will be stored inside the root directory.

@item svn update @r{(}@emph{short form}@r{:} svn up@r{)}
Recursively updates the current directory to the
latest revision. Use option @option{-r N} to update to a
specific revision.

@item svn status
Shows the status of @strong{your} working copy against 
the repository.

@item svn diff
Shows differences in unified diff format between your working
copy and the base version of the current revision selected
(usually it means the latest). If you want to compare two different
revisions you can add a @option{-r N:M} parameter.

@item svn lock @emph{filename}
Locks a file so that everybody except the lock owner can't commit
over it. This is particularly useful for binary files:
you should always try to acquire a lock before starting editing.

@end table

@c % --------------------------------------------------

@node    Gold rules on committing, How to write good log messages, Basic svn usage, Committing changes
@section Gold rules on committing
@cindex  committing

A versioning system, by definition, records everything that goes through it.
So it may be a good idea not to commit garbage or make changes that will
probably be rejected by the team. The repository mustn't be used as a
temporary file storage system (so just don't use it to transfer files from 
work to home or vice-versa!).

When you commit something, it should be an acceptable piece of work. 
Of course, it can happen that later inspection demonstrates
it's better to revert some changesets, but that's the purpose of 
having a centralized versioning system.

Avoid big commits altogether. A detailed description of your intentions 
should hit the mailing list @emph{before} even starting to write such a 
patch. Then, committing your work must happen via 
@strong{small incremental patches}. 

Also please avoid making structural tree changes (creating, 
moving, removing, renaming directories) without asking first
the repository administrator.

Everything can be reverted by @command{svn}, but that's not an 
excuse for sloppiness.

@c % --------------------------------------------------

@node    How to write good log messages, Conflicts resolution, Gold rules on committing, Committing changes
@section How to write good log messages
@cindex  log messages

Be as descriptive as possible, concisely. If your changeset was discussed on
the mailing list or at a meeting, make a clear reference to it.

Please be consistent with the message format. Use a clean english language,
employing only abbreviations contained in the glossary document.

Always prepend a dash (@minus{}) for each changeset description, 
followed by a space. This will make clear, in case of line wrapping, 
what is part of the list and what is simply a new line.

Every sentence must end with a full stop. If a particular description 
is composed by several sub-descriptions, use a colon (@samp{:}), and
use a tab space to indent the inner list.

You can use only one level of nesting for lists. If you need more, 
you are probably making an oversized commit.

An example of the log format is the following:

@example
- Change description 1.
- Change description 2:
 <tab>  - Part 1 of change description 2.
 <tab>  - Part 2 of change description 2.
- Change description 3. This particular change has a very long message
  describing this atomic commit.
@end example

@c % --------------------------------------------------

@node    Conflicts resolution, (none), How to write good log messages, Committing changes
@section Conflicts resolution
@cindex  conflicts
@cindex  merging

As in any other concurrent development system, conflicts may happen. 
this will be demanded to the official @cite{Subversion Book (ch. 3 sect. 5.4)}
for an explanation on how to handle them. 
We will just quote something to keep well in mind, however:

@quotation
In the end, it all comes down to one critical factor: user communication.
When users communicate poorly, both syntactic and semantic conflicts
increase. No system can force users to communicate perfectly, and no system
can detect semantic conflicts. So there's no point in being lulled into a
false promise that a locking system will somehow prevent conflicts; in
practice, locking seems to inhibit productivity more than anything else.
@end quotation
@cite{Version Control with Subversion, a.k.a. ``The Subversion Book''}


@c % --------------------------------------------------

@node    Using the Mailing List, License, Committing changes, Top
@chapter Using the Mailing List
@cindex  mailing list

@section Introduction and goals

This mailing list (often referred from now on simply as ``ML'') has been
created with the specific aim of coordinating the effort of the members
of our Software Engineering steering committee.

This chapter focuses on describing a set of guidelines of what
should be considered best practices whenever writing to the ML, 
in order to avoid possible troubles and thornful outcomes.

This very chapter (an approved draft) you're reading can be amended 
too. For more informations, please refer to the corresponding 
subsection, called ``A democratic discussion''.

@section About the language, some useful conventions

The English language (either the UK or the US one, but the slangwords)
is believed to be the best choice to deliver our internal
drafts and user manuals, while the external ones are kept in Italian 
to help our Customer in his revision work. 

The decision of internally using the English language descends 
from two considerations:

1) English is probably the most widely used language in the world (at
least taking in account geographical extension). Making an effort to use
it correctly during the development of this project is a good training
ground for the future, and makes @acronym{SGPEMv2} usable also by
non-Italian speakers.

2) It encourages you to use a cleaner and simplier form, since 
you're writing in a foreign language: you actually have to think 
about what you're doing in a more careful way; not only to express 
your ideas, but also to express your ideas @emph{in a way you can be 
understood}. Most people that don't read again what they typed if 
writing in their mothertongue, usually look through an email 
composed in English at least twice, in order to check out for grammar
mistakes. Therefore, it often makes easier to find also conceptual 
disasters.

Please avoid strong words or offensive language. They don't help the
discussion anyway, they represent a waste of bytes on the server, and
at least some of us consider them to be childish behaviour.

If some of us ask you to explain what you meant, or correct your
grammar, please don't lose your temper or feel blue: we're all here to
learn.

As a side note, we encourage the use of the "singular they" as a neutral
form. You can find a nice article on this by searching @emph{Wikipedia}.

This doesn't forbid you to use Italian for normal communications over
the ML.

@section Steer the wheel

Most discussions start with a draft, like this. The talking then goes on
amendating the document and, when no-one opposes it anymore, the draft is
marked as an approved guideline, and everybody is meant to (as strictly
as possible) conform to it.

Exceptions or revisions to guidelines due to a rework done by some other
process pertain to the @acronym{KA,Knowledge Area} of 
Process Improvement (see @acronym{SWEBOK} §9).

The committer could ask for some particular modalities in carrying out
this procedure, although unlikely (usually, it's an internal task).

This draft is hence subject to change in this aspect.

@section A democratic discussion

Of course, not everybody has to agree with everyone else on every
subject. We're just humans, after all; we're entitled to our opinion.
Hence, it may be necessary, at times, to set up a votation.

In a votation, if @samp{n} options are available, each voter has
@samp{n*10} points expendable. They can thus weight their decision
prioritizing one or more of the listed choices, and distributing these
points as they wish. The highest scoring option wins the votation. 
In case of even scores, ballot can happen until a clear decision 
has been reached.

Usually a maximum time to amendate a draft or to vote is declared; 
if no further points to discuss are raised in such time, the document 
is marked as agreed. The minimum number of days for a votation / to amend 
a draft is set to three.

@section Keeping the archives clean

If, by writing your response, you've to comment on things that pertain to
@emph{different} @acronym{KA}s, or if the discussion requires to 
be "branched" over different subjects, please also start a new thread, 
change the subject line, and split your own letter, even if the answer 
to a question just takes two lines.

Not only this makes easier to search throughout the archives; it makes
easier for others to reply only to those matters that concern they,
tidily continuing the tree structure of threads.

@section Diving in technicalities

E-mails should be sent out text-only, not in @acronym{HTML} format. 
This makes them faster to download, store, manipulate, and it even 
saves us from kaki-on-pink kitsch backgrounds. 
Moreover, text-only mails are (almost always) monospaced; this allows 
the more aestethical-inclined of us to integrate @acronym{ASCII}-art 
in them, like handmade diagrams.

Virtually all email clients available let you choose how you want to
send your messages to a certain address: if in @acronym{HTML}, 
plain-text or both. Please choose plain-text only.

Another important thing to keep in mind, is to set your encoding to
@acronym{UTF}-8. This makes interoperability between different and exotic
encodings possible by using a standard base. Yes, even between different
operating systems, like the one called ``98'' and the one named ``2000'' @emph{;-)}.

A simple discussion shouldn't be marked in whatever way: it has just a
meaningful subject. For example: @emph{``hello, world!''} is a bad subject; it
doesn't tell much of the contents of the message, besides that probably
it has some form of salute into it. Also, a line like 
@emph{``i've a problem''} is a bad one: it could be a problem in 
installing an operating system, in finding a bug in a program, or 
in carrying out the rubbish and feeding the cat.

An example of a good subject is @emph{``Possible buffer overflow in
recursive-sort.cc:374''}. Also @emph{``How can I stuff my cat with 
friskies?''} is a good one, albeit maybe a little bit off topic.

For documents like this, a subject line of the form @emph{``(draft)
<description>''} is a good choice. It makes it easily recognizable, and
it's like automatically asking for people to amend.

Approved drafts are marked with a date, and are copied in a separate
directory of the repository (tipically, a @samp{doc} subdirectory). A quick
TeXinfo rewrite can be performed if need arises, or if someone is willing
to spend five minutes doing so.

Every approved document contains the full text correctly amended
(whereas, during the discussion just snippets of it are changed by
diff), and starts with a date and a progressive number in its header.
The header should be in the form:

@example
----------------------------------------

(approved draft) #xxxx, [<area>]
Initially submitted by: <Name Surname>
On date: <YYYY, Month DD>
Approved by:
     <Name Surname 1>
     <Name Surname 2>
     ...
Rejected by:
     <Name Surname 1>
     ...
Reason of refusal:
    <description of the reason>
Finally approved on date: <YYYY, Month DD>

----------------------------------------
@end example

Of course, the @samp{rejected by} list should ideally be empty, or just
listing @samp{nobody}. The subject area is up to the writer to purpose,
wisely. Different areas are instantiated as need arises. Please don't
create a forest of areas; it's no use whatsoever.

Have fun, and ...

... happy hacking!

@c % --------------------------------------------------

@c include license text
@node License, Concept index, Using the Mailing List, Top
@include fdl.texi

@c % --------------------------------------------------

@node   Concept index, (none), License, Top
@unnumbered Concept Index
     
@printindex cp


@bye