File: HACKING

package info (click to toggle)
enchant 1.6.0-7
  • links: PTS, VCS
  • area: main
  • in suites: wheezy
  • size: 3,332 kB
  • sloc: cpp: 26,552; sh: 10,261; ansic: 4,571; makefile: 305
file content (102 lines) | stat: -rw-r--r-- 3,959 bytes parent folder | download | duplicates (9)
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
* Don't commit directly, instead send your diff to the authors (use
  'cvs diff -Nu').

Working in libenchant
-------------------

   When writing libenchant our priorities are

	1) Portable
	2) Maintainable & Documented
	3) Modular and well designed

    When you submit code to inclusion in libenchant, or when you modify the sources
directly on the CVS repository, please keep those things in mind.  While
performance is important please note that we do not want to hand tune code
to shave milliseconds at this point.  Well designed algorithms and data
strucutures are fertile areas for development, obfuscated code to make a
loop 3% faster is not.  Specifically, this means:

	- Clarity of design and function are paramount
	- Make sure your code does not generate warnings at all.
	- Please follow the formatting style

Formatting style
----------------

   The formatting style of libenchant is a mix of various styles, make
yourself familiar with the GNU coding standards (shipped with most
GNU/Linux systems as the standards.info file), then read the Linux
kernel coding standards and ignore Linus' jokes.  Then look at the
Gtk+ header files to get aquainted on how to write nice header files
that are almost self documenting. 

   Remember: Use 8 space tabs for indentation: that will keep your
code honest as you will be forced to split your routines in more
modular chunks (as detailed by Linus). 
   
   Emacs users can get the default indentation style with this:
  (set-c-style "K&R")
  (setq c-basic-offset 8)

   On top of that, you will have to:

	- Follow the Gtk+ cleanliness conventions for function
	  prototypes.

	- Follow the Gtk+ namespace convention for function names. 
	  module_submodule_operation

	- Make sure your code does not have a single warning (with the
	  default strong warnings that Gnumeric compiles with) before
	  your code is submited. (Although we do not advocate -Werror)

	- Every entry point to a public routine should use the
	  g_return_if_fail and g_return_val_if_fail macros to verify
	  that the parameters passed are valid.

	- Under no circunstances use magic variables.  Use typedef
	  enum { ... } type; to create enumerations.  Do not use
	  integers to hold references to enumerations, the compiler
	  can help catch various errors.

	- Use g_warning to mark spots that need to be reviewed or are
	  not finished to let me fix it eventually.

	- Do not submit code that is just a temporary workaround for a
	  full fledged feature.  i.e. don't submit a quick hack at
	  "search text" which is not designed to be expanded upon.  We
	  do not want to maintain limited features.  It is better submit an
	  implementation that has been designed to be expanded and enhanced,
	  even if it is not completely finished.

	- It is more important to be correct than to be fast.  

	- Do not optimize unnecesarly.  Do profile, do look for the
	  weak spots before applying "optimization by feeling".  This
	  is not a Ouija-based project. 

	- It is more important to keep the code maintainable and
	  readable than to be fast.  If you have a great idea about
	  optimizing the code, make sure it is implemented cleanly,
	  that there is a clean and maintainable way to do it:  

        - Fast code that is difficult to maintain has no place in
	  Gnumeric and will be dropped.

	- Follow the libenchant commenting style, which is not the Gtk
	  style;
		/* ie. use this for
		 * multi-line comments
		 */

   All of this is to ensure the libenchant code will be kept within
reasonable margins of maintainability for the future: Remember, in two years
you will probably be far too busy to maintain your own contributions, and they
might become a burden to the program maintainers.

   libenchant is intented to be a foundation for a various document centric
projects.

   Cleaning code in libenchant is more important than trying not to break
existing code.  By all means, code clean ups are always welcome.