You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
288 lines
10 KiB
288 lines
10 KiB
This file's purpose is to guide contributors and developers to help on the
|
|
digiKam project.
|
|
|
|
========================================================================
|
|
10 golden rules for starting with open source
|
|
========================================================================
|
|
|
|
Before to contribute to digiKam project, please take a look to this link:
|
|
|
|
http://schlitt.info/applications/blog/index.php?/archives/541-10-golden-rules-for-starting-with-open-source.html
|
|
|
|
========================================================================
|
|
Source code formatting:
|
|
========================================================================
|
|
|
|
Adhere to this style guide strictly while adding new code to digiKam or
|
|
working on existing code.
|
|
|
|
-------------------------------------------------------------------------
|
|
* Indentation length
|
|
-------------------------------------------------------------------------
|
|
|
|
Indent with 4 spaces exactly.
|
|
|
|
for eg:
|
|
|
|
void function()
|
|
{
|
|
....int a; // 4 spaces from beginning
|
|
....for (int i=0; i<10; i++) // 4 spaces from beginning
|
|
....{ // 4 spaces from beginning
|
|
........a = i; // 4 spaces from previous indent block
|
|
|
|
Emacs by default will indent to 4 spaces
|
|
vim users add this to you .vimrc
|
|
set tabstop=4
|
|
|
|
-------------------------------------------------------------------------
|
|
* Tabs vs Spaces
|
|
-------------------------------------------------------------------------
|
|
|
|
Absolutely no tabs. Use a sensible editor which will convert tabs to spaces.
|
|
This will reduce unnecessary changes in your cvs commits.
|
|
|
|
Emacs by default will convert tab to spaces.
|
|
For vim users, add this to your .vimrc
|
|
set expandtab
|
|
|
|
-------------------------------------------------------------------------
|
|
* Line length
|
|
-------------------------------------------------------------------------
|
|
|
|
Line length should never exceed 80 chars (unless really necessary - these
|
|
cases are rare). Having long lines greatly reduces readability of code
|
|
|
|
-------------------------------------------------------------------------
|
|
* Bracketing
|
|
-------------------------------------------------------------------------
|
|
|
|
In almost all cases, {} brackets should start on a newline and should be
|
|
aligned with previous line (follow the indentation spaces). for eg.
|
|
|
|
class A
|
|
{ //new line
|
|
...
|
|
|
|
for (int i=0; i<10; i++)
|
|
{ //new line
|
|
|
|
if (a == foobar)
|
|
{ //new line
|
|
...
|
|
}
|
|
else
|
|
{ // new line
|
|
..
|
|
}
|
|
|
|
-------------------------------------------------------------------------
|
|
* Positioning of Access modifiers
|
|
-------------------------------------------------------------------------
|
|
|
|
public, private, protected, public slots, ... should be aligned to the
|
|
beginning of the line with no margin
|
|
|
|
class A
|
|
{
|
|
public: // aligned to left
|
|
...
|
|
private slots: // aligned to left
|
|
|
|
|
|
Follow a consistent order in defining these attributes. The recommended
|
|
order is public, protected (functions), private (functions),
|
|
signals, public slots, protected slots, private slots, private (variables)
|
|
|
|
========================================================================
|
|
Class, file and Variable names:
|
|
========================================================================
|
|
|
|
-------------------------------------------------------------------------
|
|
* Class and filenames
|
|
-------------------------------------------------------------------------
|
|
|
|
- filenames should always be in lower-case
|
|
- class names should match the filenames. Capitalize the first letter and
|
|
other letters logically to improve readability
|
|
|
|
-------------------------------------------------------------------------
|
|
* Protected Member variables
|
|
-------------------------------------------------------------------------
|
|
|
|
- protected member variable names should always be of the form m_varName.
|
|
- Captilize logically so that it becomes easy to read it. Do not capitalize
|
|
the first letter after _ (Use m_varName not m_VarName)
|
|
- variable names should be indicative of their functionality and also of
|
|
the type they belong too if they are instances of tqt widgets.
|
|
for eg, QCheckBox* m_autoRotateCheckBox;
|
|
|
|
-------------------------------------------------------------------------
|
|
* Non-Member variables
|
|
-------------------------------------------------------------------------
|
|
|
|
- non-member variables should follow the same naming convention as the member
|
|
variables, except for the leading m_
|
|
|
|
-------------------------------------------------------------------------
|
|
* Private Member variables
|
|
-------------------------------------------------------------------------
|
|
|
|
- private member variables must be stored in a d private container to reduce
|
|
compilation time and improve binary compatibilty between digiKam components.
|
|
See more informations how to use a 'd' private class at this url:
|
|
|
|
http://developer.kde.org/policies/librarypolicy.html
|
|
|
|
========================================================================
|
|
Comments and Whitespace
|
|
========================================================================
|
|
|
|
Use whitespaces liberally to improve readability. Add blank lines between logical
|
|
sections of the code.
|
|
|
|
Comment as much as possible. Position comments at the beginning of the
|
|
section/line you want to comment, NEVER at the end of the line
|
|
|
|
// put your comments here
|
|
a = (b == foobar) ? 1 : -1;
|
|
|
|
a = (b == foobar) ? 1 : -1; // you are asking for trouble by putting comments here
|
|
|
|
|
|
========================================================================
|
|
Header files
|
|
========================================================================
|
|
|
|
- Add copyright to top of every file. Use the same header than others digiKam
|
|
source code.
|
|
- Double inclusion protection defines are all upper case letters and are
|
|
composed of the classname and a H suffix separated by underscore
|
|
|
|
#ifndef ANOTHERNICECLASS_H
|
|
#define ANOTHERNICECLASS_H
|
|
|
|
class AnotherNiceClass
|
|
{
|
|
...
|
|
}
|
|
|
|
#endif
|
|
|
|
- Use forward declarations as much as possible.
|
|
|
|
class QFileInfo;
|
|
|
|
class A
|
|
{
|
|
....QFileInfo* m_fileInfo;
|
|
|
|
========================================================================
|
|
General recommendations
|
|
========================================================================
|
|
|
|
Please take a look into KDE contrib page tips before to write code/patches for
|
|
digiKam project : http://techbase.kde.org/Contribute
|
|
|
|
Use the same .cpp/.h header than the rest of digiKam project.
|
|
|
|
Use a decent editor which does auto-indentation/syntax-highlighting for you.
|
|
I personally use Emacs (Renchi) or Kdevelop (Gilles).
|
|
There are excellent initializer scripts in the tdesdk
|
|
package for xemacs and vim which can substantially increase your productivity.
|
|
|
|
Just to give a taste of what i can do with emacs (and tdesdk):
|
|
|
|
* automatically insert copyright (and ifdefs) in new files.
|
|
* insertion of class function definitions for declared class
|
|
functions in header with one keystroke
|
|
* switch between header and declaration files with one keystroke
|
|
* go to corresponding definition/declaration with one keystroke
|
|
* tab completion of variable/function names already declared.
|
|
|
|
========================================================================
|
|
GDB Backtrace
|
|
========================================================================
|
|
|
|
If you found a context to crash digiKam, you can provide a backtrace using GDB debugger.
|
|
digiKam need to be compiled with all debug info else the backtrace will not suitable.
|
|
There is a configure option for that:
|
|
|
|
# make -f Makefile.cvs
|
|
# ./configure --enable-debug=full
|
|
# make
|
|
# su
|
|
# make install.
|
|
|
|
To make a backtrace with GDB use following command:
|
|
|
|
# gdb digikam
|
|
> run
|
|
> ...
|
|
> _crash here_
|
|
> ...
|
|
> bt
|
|
> _the backtrace is here_
|
|
> quit
|
|
|
|
Post this backtrace at the right place (B.K.O or devel ML) for investigations by developers.
|
|
|
|
========================================================================
|
|
Memory leak
|
|
========================================================================
|
|
|
|
To check any memory leak problem in digiKam, valgrind is your friend (http://valgrind.org)
|
|
Try this command line to use with valgrind :
|
|
|
|
valgrind --tool=memcheck --leak-check=full --error-limit=no digikam
|
|
|
|
========================================================================
|
|
Profiling with cachegrind
|
|
========================================================================
|
|
|
|
Valgrind also includes a tool to find out in which parts of your code time is spent.
|
|
|
|
valgrind --tool=callgrind digikam
|
|
|
|
Profiling can be disabled at startup to limit the output to the code you are interested in.
|
|
Start with
|
|
|
|
valgrind --tool=callgrind --instr-atstart=no digikam
|
|
|
|
and prepare the situation you want to profile. Then, in another console, start profiling with
|
|
"callgrind_control -i on" and, after the situation has passed, request a profile dump with
|
|
"callgrind_control -d".
|
|
The resulting callgrind.out files need to be viewed with the tdecachegrind program, e.g.:
|
|
|
|
tdecachegrind callgrind.out.16693.1
|
|
|
|
=================================================================================
|
|
API Documentation Validation, User Documentation Validation, Source Code Checking
|
|
=================================================================================
|
|
|
|
The following site check on a dayly basis for the a.m. errors:
|
|
www.englishbreakfastnetwork.org/krazy/
|
|
|
|
It can be very useful, in particular before major releases.
|
|
Don't trust it blindly! Sometimes they propose too advanced modifications that are no compatible with the prevailant include files.
|
|
|
|
========================================================================
|
|
Usability issues
|
|
========================================================================
|
|
|
|
OpenUsability project has define default menu structure and keyboard shortcuts:
|
|
|
|
http://wiki.openusability.org/guidelines/index.php/Appendices:Keyboard_Shortcuts
|
|
|
|
========================================================================
|
|
Generate API documentation
|
|
========================================================================
|
|
|
|
To generate API documentation, you need to install:
|
|
|
|
- Doxygen program (http://www.doxygen.org).
|
|
- Dot program (http://www.graphviz.org)
|
|
|
|
Go to 'project' sub-folder and just run doxygen binary program. A new subfolder
|
|
named 'api' will be create. Warning, this can take a while.
|