1.1 --- a/discussion.roff	Mon Jun 25 22:27:38 2012 +0200
     1.2 +++ b/discussion.roff	Tue Jun 26 13:42:18 2012 +0200
     1.3 @@ -1638,16 +1638,18 @@
     1.4  
     1.5  .H1 "Modernizing
     1.6  .P
     1.7 -The code base of mmh originates from the late seventies.
     1.8 -Through the eighties, extensive work had been done on it.
     1.9 -In the nineties, it was partly reorganized and extended.
    1.10 -Relicts from each decade have gathered in the code base.
    1.11 -My goal was to modernize the code base.
    1.12 -
    1.13 -.P
    1.14 -FIXME functional aspect only here
    1.15 -.P
    1.16 -FIXME ref to `code style' for non-functional aspects.
    1.17 +In the over thirty years of MH's existence, its code base was
    1.18 +extended more and more.
    1.19 +New features entered the project and became alternatives to the
    1.20 +existing behavior.
    1.21 +Relicts from several decades have gathered in the code base,
    1.22 +but seldom obsolete features were dropped.
    1.23 +This section describes the removing of old code
    1.24 +and the modernizing of the default setup.
    1.25 +It focuses on the functional aspect only;
    1.26 +the non-functional aspects of code style are discussed in
    1.27 +.\" FIXME REF
    1.28 +Sec. XXX.
    1.29  
    1.30  
    1.31  .H2 "Code Relicts
    1.32 @@ -2475,17 +2477,173 @@
    1.33  
    1.34  .H1 "Code Style
    1.35  .P
    1.36 -foo
    1.37 +Kernighan and Pike have emphasized the importance of style in the
    1.38 +preface of their book:
    1.39 +.[ [
    1.40 +kernighan pike practice of programming
    1.41 +.], p. x]
    1.42 +.QS
    1.43 +Chapter 1 discusses programming style.
    1.44 +Good style is so important to good programming that we have chose
    1.45 +to cover it first.
    1.46 +.QE
    1.47 +This section covers changes in mmh that were motivated by the desire
    1.48 +to improve on style.
    1.49 +Many of them follow the rules given in the quoted book.
    1.50 +.[
    1.51 +kernighan pike practice of programming
    1.52 +.]
    1.53 +
    1.54 +
    1.55 +.H2 "Style
    1.56 +.P
    1.57 +.U3 "Indentation Style
    1.58 +.P
    1.59 +Indentation styles are the holy cow of programmers.
    1.60 +Again Kernighan and Pike:
    1.61 +.[ [
    1.62 +kernighan pike practice of programming
    1.63 +.], p. 10]
    1.64 +.QS
    1.65 +Programmers have always argued about the layout of programs,
    1.66 +but the specific style is much less important than its consistent
    1.67 +application.
    1.68 +Pick one style, preferibly ours, use it consistently, and don't waste
    1.69 +time arguing.
    1.70 +.QE
    1.71 +.P
    1.72 +I agree that the constant application is most important,
    1.73 +but I believe that some styles have advantages over others.
    1.74 +For instance the indentation with tab characters only.
    1.75 +Tab characters directly map to the nesting level \(en
    1.76 +one tab, one level.
    1.77 +Tab characters are flexible because developers can adjust them to
    1.78 +whatever width they like to have.
    1.79 +There is no more need to run
    1.80 +.Pn unexpand
    1.81 +or
    1.82 +.Pn entab
    1.83 +programs to ensure the correct mixture of leading tabs and spaces.
    1.84 +The simple rules are: (1) Leading whitespace must consist of tabs only.
    1.85 +(2) Any other whitespace should consist of spaces.
    1.86 +These two rules ensure the integrity of the visual appearence.
    1.87 +Although reformating existing code should be avoided, I did it.
    1.88 +I did not waste time arguing; I just did it.
    1.89 +.Ci a485ed478abbd599d8c9aab48934e7a26733ecb1
    1.90 +
    1.91 +.U3 "Comments
    1.92 +.P
    1.93 +Section 1.6 of
    1.94 +.[ [
    1.95 +kernighan pike practice of programming
    1.96 +.], p. 23]
    1.97 +demands: ``Don't belabor the obvious.''
    1.98 +Hence, I simply removed comments like the following:
    1.99 +.VS
   1.100 +context_replace(curfolder, folder);  /* update current folder   */
   1.101 +context_save();  /* save the context file   */
   1.102 +folder_free(mp);  /* free folder structure   */
   1.103 +VE
   1.104 +.Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
   1.105 +.VS
   1.106 +seq_setcur (mp, mp->lowsel);/* set current message for folder */
   1.107 +seq_save (mp);  /* synchronize message sequences  */
   1.108 +folder_free (mp);  /* free folder/message structure  */
   1.109 +VE
   1.110 +.Ci 337338b404931f06f0db2119c9e145e8ca5a9860
   1.111 +.P
   1.112 +The names of the functions explain enough already.
   1.113 +
   1.114 +.U3 "Names
   1.115 +.P
   1.116 +Kernighan and Pike suggest:
   1.117 +``Use active names for functions''.
   1.118 +.[ [
   1.119 +kernighan pike practice of programming
   1.120 +.], p. 4]
   1.121 +One application of this rule was the rename of
   1.122 +.Fu check_charset()
   1.123 +to
   1.124 +.Fu is_native_charset() .
   1.125 +.Ci 8d77b48284c58c135a6b2787e721597346ab056d
   1.126 +The same change fixed a violation of ``Be accurate'' as well.
   1.127 +The code did not match the expectation the function suggested,
   1.128 +as it, for whatever reason, only compared the first ten characters
   1.129 +of the charset name.
   1.130 +.P
   1.131 +More important than using active names is using descriptive names.
   1.132 +Renaming the obscure function
   1.133 +.Fu m_unknown()
   1.134 +was a delightful event.
   1.135 +.Ci 611d68d19204d7cbf5bd585391249cb5bafca846
   1.136 +.P
   1.137 +Magic numbers are generally considered bad style.
   1.138 +Obviously, Kernighan and Pike agree:
   1.139 +``Give names to magic numbers''.
   1.140 +.[ [
   1.141 +kernighan pike practice of programming
   1.142 +.], p. 19]
   1.143 +One such change was naming the type of input \(en mbox or mail folder \(en
   1.144 +to be scanned:
   1.145 +.VS
   1.146 +#define SCN_MBOX (-1)
   1.147 +#define SCN_FOLD 0
   1.148 +VE
   1.149 +.Ci 7ffb36d28e517a6f3a10272056fc127592ab1c19
   1.150 +.P
   1.151 +The argument
   1.152 +.Ar outnum
   1.153 +of the function
   1.154 +.Fu scan()
   1.155 +in
   1.156 +.Fn uip/scansbr.c
   1.157 +defines the number of the message to be created.
   1.158 +If no message is to be created, the argument is misused to transport
   1.159 +program logic.
   1.160 +This lead to obscure code.
   1.161 +I improved the clarity of the code by introducing two variables:
   1.162 +.VS
   1.163 +int incing = (outnum > 0);
   1.164 +int ismbox = (outnum != 0);
   1.165 +VE
   1.166 +They cover the magic values and are used for conditions.
   1.167 +The variable
   1.168 +.Ar outnum
   1.169 +is only used when it holds an ordinary message number.
   1.170 +.Ci b8b075c77be7794f3ae9ff0e8cedb12b48fd139f
   1.171 +The clarity improvement of the change showed detours in the program logic
   1.172 +of related code parts.
   1.173 +Having the new variables with descriptive names, a more
   1.174 +staight forward implementation became appearant.
   1.175 +Before the clarification was done,
   1.176 +the possibility to improve had not be seen.
   1.177 +.Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723
   1.178 +
   1.179 +.U3 "Rework of \f(CWanno\fP
   1.180 +.P
   1.181 +At the end of their chapter on style,
   1.182 +Kernighan and Pike ask: ``But why worry about style?''
   1.183 +The following description of my rework on
   1.184 +.Pn anno
   1.185 +shows why style matters.
   1.186 +.P
   1.187 +
   1.188 +
   1.189 +
   1.190 +.P
   1.191 +goto
   1.192 +.P
   1.193 +anno rework
   1.194 +
   1.195  
   1.196  
   1.197  .H2 "Standard Code
   1.198  .P
   1.199  POSIX
   1.200  
   1.201 -.U3 "Converting to Standard Code
   1.202  .P
   1.203  One part of this task was converting obsolete code constructs
   1.204 -to standard constructs.
   1.205 +to standard replacements.
   1.206  As I'm not even thirty years old and have no more than seven years of
   1.207  Unix experience, I needed to learn about the history in retrospective.
   1.208  Older people likely have used those ancient constructs themselves
   1.209 @@ -2508,15 +2666,26 @@
   1.210  He converted large parts of the code to POSIX constructs, removing
   1.211  the conditionals compilation for now standardized features.
   1.212  I'm thankful for this task being solved.
   1.213 -I only pulled the changes into
   1.214 -mmh.
   1.215 +I only pulled the changes into mmh.
   1.216  
   1.217  
   1.218  
   1.219  
   1.220 +.H2 "Modularization
   1.221 +.P
   1.222 +The \fIMH library\fP
   1.223 +.Fn libmh.a
   1.224 +collects a bunch of standard functions that many of the MH tools need,
   1.225 +like reading the profile or context files.
   1.226 +This doesn't hurt the separation.
   1.227 +.P
   1.228 +whatnowproc
   1.229 +
   1.230 +
   1.231 +
   1.232  .H2 "Separation
   1.233  
   1.234 -.U2 "MH Directory Split
   1.235 +.U3 "MH Directory Split
   1.236  .P
   1.237  In MH and nmh, a personal setup had consisted of two parts:
   1.238  The MH profile, named
   1.239 @@ -2618,24 +2787,8 @@
   1.240  split between mail storage and personal configuration files.
   1.241  
   1.242  
   1.243 -.H2 "Modularization
   1.244 -.P
   1.245 -whatnowproc
   1.246 -.P
   1.247 -The \fIMH library\fP
   1.248 -.Fn libmh.a
   1.249 -collects a bunch of standard functions that many of the MH tools need,
   1.250 -like reading the profile or context files.
   1.251 -This doesn't hurt the separation.
   1.252  
   1.253  
   1.254 -.H2 "Style
   1.255 -.P
   1.256 -Code layout, goto, ...
   1.257 -
   1.258 -.P
   1.259 -anno rework
   1.260 -
   1.261  
   1.262  
   1.263