# HG changeset patch # User markus schnalke # Date 1340710938 -7200 # Node ID 48e28eaee6f973e7828fc067fc28a5efb4b8bd43 # Parent 97369a93ef390585482870ab5bcbe5da1462fd4a Wrote intro to Modernizing and new text about Code Style. diff -r 97369a93ef39 -r 48e28eaee6f9 discussion.roff --- 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 -