diff options
author | Reuben Thomas <rrt@sc3d.org> | 2017-02-21 12:30:50 +0000 |
---|---|---|
committer | Reuben Thomas <rrt@sc3d.org> | 2017-02-21 12:30:50 +0000 |
commit | a9d92f57b1c8c26afce9faf676d5e6eb0bd6b2c0 (patch) | |
tree | 5949c70876fd1108947b1358510899ba573202d9 | |
parent | b90435e9f241dde68f2e615135d6a7f3e1587d44 (diff) | |
download | enchant-a9d92f57b1c8c26afce9faf676d5e6eb0bd6b2c0.tar.gz |
Improve HACKING
Remove some repeated material, and split out the Emacs settings into
.dir-locals.el, so that Emacs users will get them automatically.
-rw-r--r-- | .dir-locals.el | 4 | ||||
-rw-r--r-- | HACKING | 74 |
2 files changed, 30 insertions, 48 deletions
diff --git a/.dir-locals.el b/.dir-locals.el new file mode 100644 index 0000000..127a4ad --- /dev/null +++ b/.dir-locals.el @@ -0,0 +1,4 @@ +((c-mode . ((c-file-style . "K&R") + (c-basic-offset . 8) + (tab-width . 8) + (indent-tabs-mode . t)))) @@ -18,80 +18,58 @@ Working in libenchant 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 -structures are fertile areas for development, obfuscated code to make a -loop 3% faster is not. Specifically, this means: + When you submit code for inclusion in libenchant, please keep those +things in mind. While performance is important please note that +well-designed algorithms and data structures 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. + - Make sure your code does not generate warnings - 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 + The formatting style of libenchant is a mix of various styles. Please +familiarise yourself 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 acquainted on how to write nice header files -that are almost self documenting. +kernel coding standards and ignore Linus's jokes. Then look at the +Gtk+ header files to get acquainted with 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 + Emacs users should use the supplied .dir-locals.el. + + Remember: Use tabs for indentation: that will keep your +code honest as you will be forced to split your routines into 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: + On top of that, please: - Follow the Gtk+ cleanliness conventions for function prototypes. - - Follow the Gtk+ namespace convention for function names. + - 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 submitted. (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 circumstances 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. + integers to hold enumeration values: 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. + not finished. - 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 unnecessarily. 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 - Enchant and will be dropped. + full fledged feature. We do not want to maintain limited + features. It is better to submit an implementation designed + to be expanded and enhanced, even if it is not completely + finished. - Follow the libenchant commenting style, which is not the Gtk style; @@ -104,8 +82,8 @@ 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 intended to be a foundation for a various document centric + libenchant is intended to be a foundation for a various document-centric projects. Cleaning code in libenchant is more important than trying not to break -existing code. Code clean ups are always welcome. +existing code. Code clean-ups are always welcome. |