mirror of https://gitee.com/openkylin/enchant.git
103 lines
3.9 KiB
Plaintext
103 lines
3.9 KiB
Plaintext
|
* 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.
|