Packagesearch Programming Guidelines and Hints

# Policy for Plugins

Main Identifier: Plugin Name

Additional Information:

- Author

- Version

- Location (Path, derived from library location)

  - Implicit search path order: plugins/, ../plugins/, /usr/lib/packagesearch

  - If more than one version is available use the one appearing first in the search path

Plugin file names must be of the format: lib<pluginname>.so

### Internationalisation i18n

Uses QT-Translation mechanism.

- translation files located at packagesearch/translations/
- one file per plugin, one for main application, names: <pluginname>_<lang>.ts

To add a new language

- add reference to "ts"-file to each .pro file (i.e. each plugin and packagesearch.pro)
- run lupdate packagesearch.pro and lupdate plugins/plugins.pro

To compile the translations:

- run make debug or make release within packagesearch/

### Naming Conventions

- Typenames/Const

- typenames start with a capital letter - each word in it again
- constants are written in capital letters, different words are seperated by an underscorde _

- Variables

- varibles start with a lower case letter
- member variables start with a underscore _
- pointers start with a p

- Filenames

- filenames and directories are written lowercase without underscores
- Source files .cpp, Headerfiles .h

- Functions

- if the functions argument list goes over more then two lines, the closing braclet will appear on a separate line and the line with the function name will not contain a parameter e.g.

    // this is OK
    func(aVeryLongVariableName1, aMuchMoreLongerVariableNameWhichFillsAllTheLine2,
         aVeryLongVariableNameWhichIsReallyLong3, aVeryLongVariableNameWhichIsReallyLong4);
    // if more than this:
    func (
    	aVeryLongVariableNameWhichIsReallyLong1, aMuchMuchLongerVariableName2
    	aVeryLongVariableNameWhichIsReallyLong3, aMuchMuchLongerVariableName4
    	aVeryLongVariableNameWhichIsReallyLong5, aMuchMuchLongerVariableName5
    );

### Documentation

- tool tips and status tips start with a capital letter, all following words are capitalized normally e.g. "Choose a package"
- What's this consist of normal text (i.e. sentences)

### User Interface

- options listed are to be formated as tool tips i.e. with a leading capital character an the rest capitalized normally

### Doxygen

Doxygen comments look like this:

        /** @brief This holds the package collection ready to be used.
          *
          * Use the output function for your consumers
          */

If they need only one line the closing */ must be on the same line:

        /** This manages the include widgets (but not the labels belonging to them. */

### Includes

#include <...> proceeds
#include "..."
include order:
- stl includes
- opengl includes
- qt includes
- other global includes (those with <>)
- the corresponding header for the cpp file ("xmldata.h" for xmldata.cpp)
- other local includes
Grouping:
- local includes from the same namespace are grouped together (followed by an
empty line
- includes from the same external library or directory are grouped together

### Saving

Saving happens in XML
Error handling:
- if something wasn't loaded properly we will try to set a reasonable default value
- We will not go to the next entry if loading of an element failed, so if there is a
broken tag (e.g. wrong spelling) this will break all following parts. This is done
because if we added a new item in the DTD and we have an incorrect XML file where
this entry is missing, it will use a default value and the next tag will read the
correct entry.
Saving in packagesearch:
- comments in the configuration file are not allowed