← Back to branch summary

~ubuntu-branches/debian/sid/kexi/sid

« back to all changes in this revision

Viewing changes to src/doc/dev/naming_conventions.txt

  • Committer: Package Import Robot
  • Author(s): Pino Toscano
  • Date: 2017-06-24 20:10:10 UTC
  • Revision ID: package-import@ubuntu.com-20170624201010-5lrzd5r2vwthwifp
Tags: upstream-3.0.1.1
Import upstream version 3.0.1.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/doc/dev/naming_conventions.txt
 
1
---------------------------------------------------------
 
2
 Kexi Naming Conventions
 
3
 
 
4
 These rules apply to Kexi Team developers
 
5
 There are also guidelines for future naming decissions.
 
6
 
 
7
 Started: 2003-10-17
 
8
 Copyright (C) 2003 Kexi Team
 
9
 Kexi home page: http://www.kexi-project.org/
 
10
---------------------------------------------------
 
11
 
 
12
1. Namespaces
 
13
To simplify class names and make these names shorter, we use namespaces.
 
14
 
 
15
1.1. KexiWindow ???
 
16
 
 
17
#TODO
 
18
 
 
19
2. Directories
 
20
 
 
21
plugins/<subdirs>
 
22
 any plugins such as table/query/form designers, import plugins, one subdirectory per plugin
 
23
 
 
24
widgets/<subdirs>
 
25
 general-purpose widgets
 
26
 
 
27
3rdparty/<subdirs>
 
28
 any modules that can be considered as external (not necessarily optional)
 
29
 
 
30
 
 
31
3. Creating documentation
 
32
 
 
33
- Doxygen (www.doxygen.org) is used for generating Kexi developer documentation.
 
34
- default target directory of these docs in html format is: doc/html for all sources
 
35
- one step (..) up from mentioned dirs are places for .doxygen project files used
 
36
  for docs generating
 
37
- Single-line comments are created begginning with: //!
 
38
- Multi-line comments are created begginning with /*! or /**
 
39
- Style of comments (/*! of /**) for given file should be preserved
 
40
 
 
41
Example 3.1: Comments for non-void functions, adding information about parameters:
 
42
 
 
43
/*! Displays value of \a x.
 
44
 \return true if displaying is successfull */
 
45
bool display(int x);
 
46
 
 
47
Notes for example:
 
48
-\return special Doxygen's  tag is used to describe that we return
 
49
something in the method (\returns will not work for Doxygen!).
 
50
-Clause should be started from capital letter and terminated with a dot.
 
51
-"\a" special tag should be used before inserting argument names (names are
 
52
equal to these from the method's definition) - the names will be therefore
 
53
highlighted by Doxygen.
 
54
 
 
55
-For more sophisticated methods (with more arguments), you can as well
 
56
use \param tag, e.g.:
 
57
 
 
58
/*!
 
59
\param x horizontal position
 
60
\param y vertical position
 
61
\param col color of the box
 
62
*/
 
63
 
 
64
-Methods/functions should be documented in header files (.h), not in implementation
 
65
 files. This allows easier inspection for users of the source code.
 
66
-Comments from implementation files can be turned into
 
67
 additional documentation, if really needed (when we use "/*!")
 
68
 and this also will be included to generated docs if Doxygen project has enabled appropriate
 
69
 option for doing this.
 
70
-Classes should be also documented -comments put just as the lines
 
71
 before "class keyword.
 
72
 
 
73
-to add reference to similar or related function, use \sa tag, e.g.:
 
74
/*! blablabla
 
75
 \sa bleble
 
76
*/
 
77
 
 
78
-to mark a code fragment that someting is TO DO, you can use \todo tag, e.g.:
 
79
 
 
80
/*! \todo (js) it is so hard to implement!
 
81
*/
 
82
 
 
83
-example above shows that adding e.g. own nick inside the brackets what can help
 
84
to recognise who marked given fragment.
 
85
 
 
86
4. Indentation
 
87
4.1 We use 2-spaces indentation. Do not use tabs.
 
88
example:
 
89
        QString         objectName(); //wrong
 
90
  QString objectName(); //ok
 
91
 
 
92
Rule: don't use many spaces or tabs between words.
 
93
 
 
94
4.2 To avoid many indentation levels, we can use:
 
95
 
 
96
void mymethod()
 
97
{
 
98
  if (!something)
 
99
    return;
 
100
  if (!something_else && .....)
 
101
    return;
 
102
  do_something();
 
103
}
 
104
 
 
105
 instead of:
 
106
 
 
107
void mymethod()
 
108
{
 
109
        if (something) {
 
110
                if(something_else && .....) {
 
111
                        do_something;
 
112
                }
 
113
        }
 
114
}
 
115
 
 
116
This is good, because made qt and kde sources readable.
 
117
 
 
118
4.3 Indentation within classes declaration
 
119
 
 
120
namespace MyNamespace {
 
121
 
 
122
class MyClass {
 
123
  public:
 
124
    MyClass();
 
125
    void method();
 
126
  protected:
 
127
};
 
128
 
 
129
}