--- a/discussion.roff	Mon Jun 25 22:27:38 2012 +0200
+++ b/discussion.roff	Tue Jun 26 13:42:18 2012 +0200
@@ -1638,16 +1638,18 @@
 
 .H1 "Modernizing
 .P
-The code base of mmh originates from the late seventies.
-Through the eighties, extensive work had been done on it.
-In the nineties, it was partly reorganized and extended.
-Relicts from each decade have gathered in the code base.
-My goal was to modernize the code base.
-
-.P
-FIXME functional aspect only here
-.P
-FIXME ref to `code style' for non-functional aspects.
+In the over thirty years of MH's existence, its code base was
+extended more and more.
+New features entered the project and became alternatives to the
+existing behavior.
+Relicts from several decades have gathered in the code base,
+but seldom obsolete features were dropped.
+This section describes the removing of old code
+and the modernizing of the default setup.
+It focuses on the functional aspect only;
+the non-functional aspects of code style are discussed in
+.\" FIXME REF
+Sec. XXX.
 
 
 .H2 "Code Relicts
@@ -2475,17 +2477,173 @@
 
 .H1 "Code Style
 .P
-foo
+Kernighan and Pike have emphasized the importance of style in the
+preface of their book:
+.[ [
+kernighan pike practice of programming
+.], p. x]
+.QS
+Chapter 1 discusses programming style.
+Good style is so important to good programming that we have chose
+to cover it first.
+.QE
+This section covers changes in mmh that were motivated by the desire
+to improve on style.
+Many of them follow the rules given in the quoted book.
+.[
+kernighan pike practice of programming
+.]
+
+
+.H2 "Style
+.P
+.U3 "Indentation Style
+.P
+Indentation styles are the holy cow of programmers.
+Again Kernighan and Pike:
+.[ [
+kernighan pike practice of programming
+.], p. 10]
+.QS
+Programmers have always argued about the layout of programs,
+but the specific style is much less important than its consistent
+application.
+Pick one style, preferibly ours, use it consistently, and don't waste
+time arguing.
+.QE
+.P
+I agree that the constant application is most important,
+but I believe that some styles have advantages over others.
+For instance the indentation with tab characters only.
+Tab characters directly map to the nesting level \(en
+one tab, one level.
+Tab characters are flexible because developers can adjust them to
+whatever width they like to have.
+There is no more need to run
+.Pn unexpand
+or
+.Pn entab
+programs to ensure the correct mixture of leading tabs and spaces.
+The simple rules are: (1) Leading whitespace must consist of tabs only.
+(2) Any other whitespace should consist of spaces.
+These two rules ensure the integrity of the visual appearence.
+Although reformating existing code should be avoided, I did it.
+I did not waste time arguing; I just did it.
+.Ci a485ed478abbd599d8c9aab48934e7a26733ecb1
+
+.U3 "Comments
+.P
+Section 1.6 of
+.[ [
+kernighan pike practice of programming
+.], p. 23]
+demands: ``Don't belabor the obvious.''
+Hence, I simply removed comments like the following:
+.VS
+context_replace(curfolder, folder);  /* update current folder   */
+context_save();  /* save the context file   */
+folder_free(mp);  /* free folder structure   */
+VE
+.Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
+.VS
+seq_setcur (mp, mp->lowsel);/* set current message for folder */
+seq_save (mp);  /* synchronize message sequences  */
+folder_free (mp);  /* free folder/message structure  */
+VE
+.Ci 337338b404931f06f0db2119c9e145e8ca5a9860
+.P
+The names of the functions explain enough already.
+
+.U3 "Names
+.P
+Kernighan and Pike suggest:
+``Use active names for functions''.
+.[ [
+kernighan pike practice of programming
+.], p. 4]
+One application of this rule was the rename of
+.Fu check_charset()
+to
+.Fu is_native_charset() .
+.Ci 8d77b48284c58c135a6b2787e721597346ab056d
+The same change fixed a violation of ``Be accurate'' as well.
+The code did not match the expectation the function suggested,
+as it, for whatever reason, only compared the first ten characters
+of the charset name.
+.P
+More important than using active names is using descriptive names.
+Renaming the obscure function
+.Fu m_unknown()
+was a delightful event.
+.Ci 611d68d19204d7cbf5bd585391249cb5bafca846
+.P
+Magic numbers are generally considered bad style.
+Obviously, Kernighan and Pike agree:
+``Give names to magic numbers''.
+.[ [
+kernighan pike practice of programming
+.], p. 19]
+One such change was naming the type of input \(en mbox or mail folder \(en
+to be scanned:
+.VS
+#define SCN_MBOX (-1)
+#define SCN_FOLD 0
+VE
+.Ci 7ffb36d28e517a6f3a10272056fc127592ab1c19
+.P
+The argument
+.Ar outnum
+of the function
+.Fu scan()
+in
+.Fn uip/scansbr.c
+defines the number of the message to be created.
+If no message is to be created, the argument is misused to transport
+program logic.
+This lead to obscure code.
+I improved the clarity of the code by introducing two variables:
+.VS
+int incing = (outnum > 0);
+int ismbox = (outnum != 0);
+VE
+They cover the magic values and are used for conditions.
+The variable
+.Ar outnum
+is only used when it holds an ordinary message number.
+.Ci b8b075c77be7794f3ae9ff0e8cedb12b48fd139f
+The clarity improvement of the change showed detours in the program logic
+of related code parts.
+Having the new variables with descriptive names, a more
+staight forward implementation became appearant.
+Before the clarification was done,
+the possibility to improve had not be seen.
+.Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723
+
+.U3 "Rework of \f(CWanno\fP
+.P
+At the end of their chapter on style,
+Kernighan and Pike ask: ``But why worry about style?''
+The following description of my rework on
+.Pn anno
+shows why style matters.
+.P
+
+
+
+.P
+goto
+.P
+anno rework
+
 
 
 .H2 "Standard Code
 .P
 POSIX
 
-.U3 "Converting to Standard Code
 .P
 One part of this task was converting obsolete code constructs
-to standard constructs.
+to standard replacements.
 As I'm not even thirty years old and have no more than seven years of
 Unix experience, I needed to learn about the history in retrospective.
 Older people likely have used those ancient constructs themselves
@@ -2508,15 +2666,26 @@
 He converted large parts of the code to POSIX constructs, removing
 the conditionals compilation for now standardized features.
 I'm thankful for this task being solved.
-I only pulled the changes into
-mmh.
+I only pulled the changes into mmh.
+
+
+
 
+.H2 "Modularization
+.P
+The \fIMH library\fP
+.Fn libmh.a
+collects a bunch of standard functions that many of the MH tools need,
+like reading the profile or context files.
+This doesn't hurt the separation.
+.P
+whatnowproc
 
 
 
 .H2 "Separation
 
-.U2 "MH Directory Split
+.U3 "MH Directory Split
 .P
 In MH and nmh, a personal setup had consisted of two parts:
 The MH profile, named
@@ -2618,24 +2787,8 @@
 split between mail storage and personal configuration files.
 
 
-.H2 "Modularization
-.P
-whatnowproc
-.P
-The \fIMH library\fP
-.Fn libmh.a
-collects a bunch of standard functions that many of the MH tools need,
-like reading the profile or context files.
-This doesn't hurt the separation.
 
 
-.H2 "Style
-.P
-Code layout, goto, ...
-
-.P
-anno rework
-