* updated HACKING

1 files changed, 13 insertions, 10 deletions

diff --git a/HACKING b/HACKING
index 6873989..26c09f5 100644
--- a/HACKING
+++ b/HACKING
@@ -1,11 +1,11 @@
 * HACKING
 
-  Here are some guidelines for hacking on the 'mu' source code. Note, this is
-  fairly long list. This is not meant to discourage anyone from working on the
-  mu source code; I think most of the rules are common sense anyway, and some
-  of the more stylistic-aesthetic rules are clearly visible in current source
-  code, so as long as any new code 'fits in', it should go a long way in
-  satisfying the rules.
+  Here are some guidelines for hacking on the 'mu' source code. This is fairly
+  long list -- this is not meant to discourage anyone from working on the mu
+  source code; I think most of the rules are common sense anyway, and some of
+  the more stylistic-aesthetic rules are clearly visible in current source code,
+  so as long as any new code 'fits in', it should go a long way in satisfying
+  the rules.
 
 ** Coding style
 
@@ -47,10 +47,13 @@
 	....
       }
 
+      There is no non-aesthetic reason for this.
 
    10. in C code, variable-declarations are at the beginning of a block; in
        principle, C++ follows that same guideline, unless for heavy yet
-       uncertain initializations following RAII.
+       uncertain initializations following RAII. In C code, the declaration does
+       *not* initialize the variable. This will give the compiler a chance to
+       warn us if the variable is not initialized in a certain code path.
 
    11. returned strings of type char* must be freed by the caller; if they are
        not to be freed, 'const char*' should be used instead
@@ -68,12 +71,12 @@
      with --quiet)
    - g_warning is for problems the user may be able to do something about (and
      they are written on stderr)
-   - g_critical is for serious, internal problems (g_return_if_fail and
+   - g_critical is for mu bugs, serious, internal problems (g_return_if_fail and
      friends use this). (and they are written on stderr)
    - don't use g_error
 
-   if you just want to log something in the log file, use MU_LOG_WRITE, as
-   defined in mu-util.h
+   if you just want to log something in the log file without writing to screen,
+   use MU_LOG_WRITE, as defined in mu-util.h
 
 
 #+ Local Variables: ***