File: README.developer

package info (click to toggle)
shogun 0.6.3-1
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 8,688 kB
  • ctags: 6,563
  • sloc: cpp: 61,677; python: 5,233; sh: 2,767; makefile: 555; objc: 37
file content (205 lines) | stat: -rw-r--r-- 5,685 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
CODING CONVENTIONS:

FORMATTING:

- indenting uses stroustrup style with tabsize 4, i.e. for emacs use in your
	~/.emacs

	(add-hook 'c-mode-common-hook
	 (lambda ()
	  (show-paren-mode 1)
	  (setq indent-tabs-mode t)
	  (c-set-style "stroustrup")
	  (setq tab-width 4)))


	for vim in ~/.vimrc

	set cindent         " C style indenting
	set ts=4            " tabstop 
	set sw=4            " shiftwidth

- avoid whitespaces at end of lines and never use them for indentation; only
ever use tabs for indentations

- semicolons and commas ;, should be placed directly after a variable/statement

  x+=1;
  set_cache_size(0);

  for (int i=0; i<10; i++)
      ...

- brackets () and (greater/lower) equal sign ><= should should not contain
  unecessary spaces, e.g:

  int a=1;
  int b=kernel->compute();

  if (a==1)
  {
  }

  exceptions are logical subunits

  if ( (a==1) && (b==1) )
  {
  }


- breaking long lines and strings
	limit yourselves to 80 columns

	for (INT vec=params->start; vec<params->end &&
			!CSignal::cancel_computations(); vec++)
	{
		//foo
	}

	however exceptions are OK if readability is increased (as in function definitions)

- don't put multiple assignments on a single line

- functions look like

	INT* fun(INT* foo)
	{
		return foo;
	}

  and are separated by a newline, e.g:

	INT* fun1(INT* foo1)
	{
		return foo;
	}

	INT* fun2(INT* foo2)
	{
		return foo2;
	}

- same for if () else clauses, while/for loops

	if (foo)
		do_stuff();

	if (foo)
	{
		do_stuff();
		do_more();
	}

MACROS & IFDEFS:

- use macros sparingly
- avoid defining constants using macros (bye bye typechecking), use

const int FOO=5; 

or enums (when defining several realted constants)

instead

- use ifdefs sparingly (really limit yourself to the ones necessary)
  as their extreme usage makes the code completely unreadable. to achieve
  that it may be necessary to wrap a function of (e.g. for
		  pthread_create()/CreateThread()/thread_create() a wrapper function to create a
		  thread and inside of it the ifdefs to do it the solaris/win32/posix way)
- if you need to use ifdefs always comment the corresponding #else / #endif
  in the following way:

#ifdef HAVE_PYTHON
  ...
#else //HAVE_PYTHON
  ...
#endif //HAVE_PYTHON

TYPES:
- types (use only these!):
	CHAR	(8bit char(maybe signed or unsigned))
	BYTE	(8bit unsigned char)
	WORD	(16bit unsigned short)
	UINT	(32bit unsinged int)
	INT		(32bit int)
	LONG	(64bit int)
	DREAL	(double)
	LONGREAL (long double)

	exceptions: file IO / matlab interface

- classes must be (directly or indirectly) derived from CSGObject

- don't use fprintf/printf, but SG_DEBUG/SG_INFO/SG_WARNING/SG_ERROR/SG_PRINT (if in a from
		CSGObject derived object) or the static SG_SDEBUG/... functions elsewise

FUNCTIONS:

- Functions should be short and sweet, and do just one thing.  They should fit
  on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, as we all
  know), and do one thing and do that well.
- Another measure of the function is the number of local variables.  They
  shouldn't exceed 5-10, or you're doing something wrong.  Re-think the
  function, and split it into smaller pieces.  A human brain can
  generally easily keep track of about 7 different things, anything more
  and it gets confused.  You know you're brilliant, but maybe you'd like
  to understand what you did 2 weeks from now.
 
GETTING / SETTING OBJECTS

If a class stores a pointer to an object it should call SG_REF(obj) to
increase the objects reference count and SG_UNREF(obj) on class desctruction (which will
decrease the objects reference count and call the objects destructor if ref_count()==0.
Note that the caller (from within C++) of any get_* function returning an object should
also call SG_UNREF(obj) when done with the object. This makes the swig wrapped interfaces
automagically take care of object destruction.

If a class function returns a new object this has to be stated in the corresponding swig
.i file for cleanup to work, e.g. if classify() returns a new CLabels then the .i file
should contain %newobject CClassifier::classify();
 
NAMING CONVENTIONS:

- naming variables:
	- in classes are member variables are named like m_feature_vector (to avoid
			shadowing and the often hard to find bugs shadowing causes)
	- parameters (in functions) shall be named e.g. feature_vector
	- don't use meaningless variable names, it is however fine to use short names 
	like i,j,k etc in loops
	- class names start with 'C', each syllable/subword starts with a capital letter,
	 e.g. CStringFeatures

- constants/defined objects are UPPERCASE, i.e. REALVALUED

- function are named like get_feature_vector() and should be limited to as few arguments as
possible (no monster functions with > 5 arguments please)

- objects which can deal with features of type DREAL and class SIMPLE don't need
to contain Real/Simple in class name

-others are required to clarify class/type they can handle, e.g.
CSparseByteLinearKernel, CSparseGaussianKernel


-variable and function names are all lowercase (except for class Con/Destructors)
syllables/subwords are separated by '_', e.g. compute_kernel_value(), my_local_variable

-class member variables all start with m_, e.g. m_member (this is to avoid shadowing)

- features
	-featureclass Simple/Sparse
		-featuretype Real/Byte/...
- preprocessors
	-featureclass Simple/Sparse
		-featuretype Real/Byte/...
- kernel
	-featureclass Simple/Sparse
		-featuretype Real/Byte/...
			-kerneltype Linear/Gaussian/...

VERSIONING SCHEME:

- an automagic version will be created from the date of the last svn update.
if that is not enough make releases:

e.g.: svn cp trunk releases/shogun_0.1.0