docs/master: discussion.roff comparison

comparison discussion.roff @ 118:48e28eaee6f9

Wrote intro to Modernizing and new text about Code Style.

author	markus schnalke <meillo@marmaro.de>
date	Tue, 26 Jun 2012 13:42:18 +0200
parents	4fbd14dc5e91
children	e49780100ffb

comparison

equal deleted inserted replaced

-:97369a93ef39
+:48e28eaee6f9
 .H1 "Modernizing
 .P
-The code base of mmh originates from the late seventies.
+In the over thirty years of MH's existence, its code base was
-Through the eighties, extensive work had been done on it.
+extended more and more.
-In the nineties, it was partly reorganized and extended.
+New features entered the project and became alternatives to the
-Relicts from each decade have gathered in the code base.
+existing behavior.
-My goal was to modernize the code base.
+Relicts from several decades have gathered in the code base,
+but seldom obsolete features were dropped.
-.P
+This section describes the removing of old code
-FIXME functional aspect only here
+and the modernizing of the default setup.
-.P
+It focuses on the functional aspect only;
-FIXME ref to `code style' for non-functional aspects.
+the non-functional aspects of code style are discussed in
+.\" FIXME REF
+Sec. XXX.
 .H2 "Code Relicts
 .P
 My position to drop obsolete functions of mmh, in order to remove old code,
 .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
 and have suffered from their incompatibilities and have longed for
 standardization.
 task of converting the ancient code constructs to standardized ones.
 Luckily, Lyndon Nerenberg focused on this task at the nmh project.
 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
+I only pulled the changes into mmh.
-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
 .Fn \&.mh_profile
 and being located directly in the user's home directory.
 de-facto is an improvement.
 However, the main achievement is the
 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
 .H1 "Concept Exploitation/Homogeneity

Mercurial > docs > master

comparison discussion.roff @ 118:48e28eaee6f9