← Back to branch summary

~ubuntu-branches/ubuntu/raring/clucene-core/raring-proposed

« back to all changes in this revision

Viewing changes to doc/coding standards.txt

  • Committer: Package Import Robot
  • Author(s): Fathi Boudra
  • Date: 2012-08-11 09:33:38 UTC
  • mfrom: (1.1.5)
  • Revision ID: package-import@ubuntu.com-20120811093338-fgrx41ftqew3qt6a
Tags: 2.3.3.4-1
http://bugs.debian.org/661703
* New upstream release (Closes: #661703).
* Convert package to multiarch.
* Drop obsolete patches:
  - 01_add_missing_include_bug505667.diff
  - 02_posixness_fix_bug530308.diff
* Add patches:
  - Fixing_ZLIB_configuration_in_shared_CMakeLists.patch
  - Fix-pkgconfig-file-by-adding-clucene-shared-library.patch
  - Install-contribs-lib.patch
  - multiarch.patch
* Update debian/compat: bump to 8.
* Update debian/control:
  - update build dependencies (add cmake, libboost-dev and libz-dev).
  - bump Standards-Version to 3.9.3.
  - rename packages due to ABI bump: libclucene0ldbl -> libclucene-core1.
  - add libclucene-contribs1 package.
* Update debian/rules:
  - rewrite to use CMake.
  - add multiarch support.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/coding standards.txt
 
1
Coding Style
 
2
------------
 
3
 
 
4
CLucene follows a hybrid coding style. Because of the nature of the code being
 
5
a java port, there are naturally some java like syntax.
 
6
 
 
7
* Never use CL_NS_USE(x) in a header file (use CL_NS(x):: for each class), it defeats the purpose of namespaces.
 
8
* Use CL_NS_USE(x) in .cpp files if there are more than a few usages of that namespace.
 
9
 
 
10
 
 
11
Headers:
 
12
* _headername.h headers are private, and will not be distributed. Don't include these files from public headers.
 
13
* The shared library is not distributed, except for: SharedHeader.h and clucene-config.h
 
14
* Keep _ifdef's in public headers to an absolute minimum.
 
15
* Public headers should contain only classes that are exported (class CLUCENE_EXPORT classname).
 
16
* All classes should have a destructor, 
 
17
  the destructor should be virtual if there is any chance of the class being overridden
 
18
 
 
19
Documentation:
 
20
Although CLucene documentation is not complete, it would be nice to see documentation created for new files.
 
21
We used doxygen to create documentation. 2 basic formats of documentation are:
 
22
 
 
23
/** documentation must have ** to be included */
 
24
void function();
 
25
void function2(); //< can also document functions retrospectively by adding <
 
26
 
 
27
 
 
28
/** 
 
29
* You can also document memory with the special @memory alias.
 
30
* @memory you must delete data returned from this function using _CLDELETE 
 
31
*/
 
32
Object createObject();
 
33
 
 
34
 
 
35
Cross platform specifics:
 
36
* Use macros provided in shared project. This applies to data types and functions
 
37
* static const int32_t x=1; Should be coded as: Use LUCENE_STATIC_CONSTANT (int32_t, x=1). Else it is not portable.
 
38
* Static objects should not be initialised in the class header. ( class x{ static object a; }; ). This will not work
 
39
  everywhere. Instead use a getter.
 
40
  
 
41
  class x{ 
 
42
    static object* a; 
 
43
  public:
 
44
    static Object* getA(); 
 
45
    static void CLUCENE_LOCAL _shutdown();
 
46
  }; 
 
47
  
 
48
  Then in the implementation code
 
49
  
 
50
  Object* x::a = NULL;
 
51
  Object* x::getA(){
 
52
    if ( a == NULL )
 
53
        x::a = _CLNEW Object;
 
54
    return a;
 
55
  }
 
56
  void x::_shutdown(){
 
57
    _CLDELETE(a);
 
58
  }
 
59
  
 
60
  In CLucene/StdHeader.cpp, add x::_shutdown() to the list _lucene_shutdown function.
 
61
  
 
62
* This is bad:
 
63
 
 
64
    class x{
 
65
        LUCENE_STATIC_CONSTANT(int32_t, x=1)
 
66
        void func( int32_t value=x);
 
67
    };
 
68
  
 
69
  This will fail on some platforms. It is better to do:
 
70
  int32_t value=-1 (-1 should be some logical value, not necessarily -1).
 
71
  then in the implementation, check if -1 and default to the x static constant.
 
72
* Try and use the functions in util/Array.h instead of Void Map/List functions. Void Map/List will be deprecated for public access
 
73
* Most compilers don't complain about this (in normal mode), but we require pedantic mode behaviour. Some important things for this are:
 
74
  1. Initialise variables in correct order as in the class
 
75
     class x{
 
76
        int a;
 
77
        int b;
 
78
        x():
 
79
            b(12),
 
80
            a(11)   //THIS IS WRONG! a is initialised after b.
 
81
        {
 
82
        }
 
83
     };
 
84
 
 
85
Good development tips
 
86
---------------------
 
87
When developing, use the available clucene debugging tools:
 
88
* _CND_DEBUG - condition debugging, an 'assert' type system (or configure with --enable-cnddebug)
 
89
 
 
90
Good performance tips:
 
91
----------------------
 
92
CLucene has a lot of new changes to help improve performance.
 
93
Some of them are still being tuned...
 
94
 
 
95
MSVC profiling tutorial:
 
96
http://webserver.tc.cornell.edu/services/edu/topics/Performance/Profiling/more.asp
 
97
 
 
98
For GCC see gprof
 
99
you can enable gprof by configuring with ENABLE_GPROF
 
100
 
 
101
Developing
 
102
----------
 
103
When developing, please keep in mind cross-platform issues and also
 
104
character set issues (unicode/ascii).
 
105
 
 
106
Hint:
 
107
To do a quick test to see if the code compiles
 
108
run this command from the root directory of clucene.
 
109
It will compile all the CLucene code monolithically.
 
110
 
 
111
    % test-pedantic
 
112
    
 
113
This will do a quick compile then run all the clucene tests.