Merge pull request pyenchant#93 from rrthomas/master

Improve HACKING

.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))))

HACKING

@@ -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.