diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 287 |
1 files changed, 287 insertions, 0 deletions
diff --git a/HACKING b/HACKING new file mode 100644 index 00000000..cd6690f3 --- /dev/null +++ b/HACKING @@ -0,0 +1,287 @@ +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 qt 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 kdesdk +package for xemacs and vim which can substantially increase your productivity. + +Just to give a taste of what i can do with emacs (and kdesdk): + +* 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 kcachegrind program, e.g.: + +kcachegrind 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. |