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
117:97369a93ef39 118:48e28eaee6f9
1636 1636
1637 1637
1638 1638
1639 .H1 "Modernizing 1639 .H1 "Modernizing
1640 .P 1640 .P
1641 The code base of mmh originates from the late seventies. 1641 In the over thirty years of MH's existence, its code base was
1642 Through the eighties, extensive work had been done on it. 1642 extended more and more.
1643 In the nineties, it was partly reorganized and extended. 1643 New features entered the project and became alternatives to the
1644 Relicts from each decade have gathered in the code base. 1644 existing behavior.
1645 My goal was to modernize the code base. 1645 Relicts from several decades have gathered in the code base,
1646 1646 but seldom obsolete features were dropped.
1647 .P 1647 This section describes the removing of old code
1648 FIXME functional aspect only here 1648 and the modernizing of the default setup.
1649 .P 1649 It focuses on the functional aspect only;
1650 FIXME ref to `code style' for non-functional aspects. 1650 the non-functional aspects of code style are discussed in
1651 .\" FIXME REF
1652 Sec. XXX.
1651 1653
1652 1654
1653 .H2 "Code Relicts 1655 .H2 "Code Relicts
1654 .P 1656 .P
1655 My position to drop obsolete functions of mmh, in order to remove old code, 1657 My position to drop obsolete functions of mmh, in order to remove old code,
2473 2475
2474 2476
2475 2477
2476 .H1 "Code Style 2478 .H1 "Code Style
2477 .P 2479 .P
2478 foo 2480 Kernighan and Pike have emphasized the importance of style in the
2481 preface of their book:
2482 .[ [
2483 kernighan pike practice of programming
2484 .], p. x]
2485 .QS
2486 Chapter 1 discusses programming style.
2487 Good style is so important to good programming that we have chose
2488 to cover it first.
2489 .QE
2490 This section covers changes in mmh that were motivated by the desire
2491 to improve on style.
2492 Many of them follow the rules given in the quoted book.
2493 .[
2494 kernighan pike practice of programming
2495 .]
2496
2497
2498 .H2 "Style
2499 .P
2500 .U3 "Indentation Style
2501 .P
2502 Indentation styles are the holy cow of programmers.
2503 Again Kernighan and Pike:
2504 .[ [
2505 kernighan pike practice of programming
2506 .], p. 10]
2507 .QS
2508 Programmers have always argued about the layout of programs,
2509 but the specific style is much less important than its consistent
2510 application.
2511 Pick one style, preferibly ours, use it consistently, and don't waste
2512 time arguing.
2513 .QE
2514 .P
2515 I agree that the constant application is most important,
2516 but I believe that some styles have advantages over others.
2517 For instance the indentation with tab characters only.
2518 Tab characters directly map to the nesting level \(en
2519 one tab, one level.
2520 Tab characters are flexible because developers can adjust them to
2521 whatever width they like to have.
2522 There is no more need to run
2523 .Pn unexpand
2524 or
2525 .Pn entab
2526 programs to ensure the correct mixture of leading tabs and spaces.
2527 The simple rules are: (1) Leading whitespace must consist of tabs only.
2528 (2) Any other whitespace should consist of spaces.
2529 These two rules ensure the integrity of the visual appearence.
2530 Although reformating existing code should be avoided, I did it.
2531 I did not waste time arguing; I just did it.
2532 .Ci a485ed478abbd599d8c9aab48934e7a26733ecb1
2533
2534 .U3 "Comments
2535 .P
2536 Section 1.6 of
2537 .[ [
2538 kernighan pike practice of programming
2539 .], p. 23]
2540 demands: ``Don't belabor the obvious.''
2541 Hence, I simply removed comments like the following:
2542 .VS
2543 context_replace(curfolder, folder); /* update current folder */
2544 context_save(); /* save the context file */
2545 folder_free(mp); /* free folder structure */
2546 VE
2547 .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
2548 .VS
2549 seq_setcur (mp, mp->lowsel);/* set current message for folder */
2550 seq_save (mp); /* synchronize message sequences */
2551 folder_free (mp); /* free folder/message structure */
2552 VE
2553 .Ci 337338b404931f06f0db2119c9e145e8ca5a9860
2554 .P
2555 The names of the functions explain enough already.
2556
2557 .U3 "Names
2558 .P
2559 Kernighan and Pike suggest:
2560 ``Use active names for functions''.
2561 .[ [
2562 kernighan pike practice of programming
2563 .], p. 4]
2564 One application of this rule was the rename of
2565 .Fu check_charset()
2566 to
2567 .Fu is_native_charset() .
2568 .Ci 8d77b48284c58c135a6b2787e721597346ab056d
2569 The same change fixed a violation of ``Be accurate'' as well.
2570 The code did not match the expectation the function suggested,
2571 as it, for whatever reason, only compared the first ten characters
2572 of the charset name.
2573 .P
2574 More important than using active names is using descriptive names.
2575 Renaming the obscure function
2576 .Fu m_unknown()
2577 was a delightful event.
2578 .Ci 611d68d19204d7cbf5bd585391249cb5bafca846
2579 .P
2580 Magic numbers are generally considered bad style.
2581 Obviously, Kernighan and Pike agree:
2582 ``Give names to magic numbers''.
2583 .[ [
2584 kernighan pike practice of programming
2585 .], p. 19]
2586 One such change was naming the type of input \(en mbox or mail folder \(en
2587 to be scanned:
2588 .VS
2589 #define SCN_MBOX (-1)
2590 #define SCN_FOLD 0
2591 VE
2592 .Ci 7ffb36d28e517a6f3a10272056fc127592ab1c19
2593 .P
2594 The argument
2595 .Ar outnum
2596 of the function
2597 .Fu scan()
2598 in
2599 .Fn uip/scansbr.c
2600 defines the number of the message to be created.
2601 If no message is to be created, the argument is misused to transport
2602 program logic.
2603 This lead to obscure code.
2604 I improved the clarity of the code by introducing two variables:
2605 .VS
2606 int incing = (outnum > 0);
2607 int ismbox = (outnum != 0);
2608 VE
2609 They cover the magic values and are used for conditions.
2610 The variable
2611 .Ar outnum
2612 is only used when it holds an ordinary message number.
2613 .Ci b8b075c77be7794f3ae9ff0e8cedb12b48fd139f
2614 The clarity improvement of the change showed detours in the program logic
2615 of related code parts.
2616 Having the new variables with descriptive names, a more
2617 staight forward implementation became appearant.
2618 Before the clarification was done,
2619 the possibility to improve had not be seen.
2620 .Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723
2621
2622 .U3 "Rework of \f(CWanno\fP
2623 .P
2624 At the end of their chapter on style,
2625 Kernighan and Pike ask: ``But why worry about style?''
2626 The following description of my rework on
2627 .Pn anno
2628 shows why style matters.
2629 .P
2630
2631
2632
2633 .P
2634 goto
2635 .P
2636 anno rework
2637
2479 2638
2480 2639
2481 .H2 "Standard Code 2640 .H2 "Standard Code
2482 .P 2641 .P
2483 POSIX 2642 POSIX
2484 2643
2485 .U3 "Converting to Standard Code
2486 .P 2644 .P
2487 One part of this task was converting obsolete code constructs 2645 One part of this task was converting obsolete code constructs
2488 to standard constructs. 2646 to standard replacements.
2489 As I'm not even thirty years old and have no more than seven years of 2647 As I'm not even thirty years old and have no more than seven years of
2490 Unix experience, I needed to learn about the history in retrospective. 2648 Unix experience, I needed to learn about the history in retrospective.
2491 Older people likely have used those ancient constructs themselves 2649 Older people likely have used those ancient constructs themselves
2492 and have suffered from their incompatibilities and have longed for 2650 and have suffered from their incompatibilities and have longed for
2493 standardization. 2651 standardization.
2506 task of converting the ancient code constructs to standardized ones. 2664 task of converting the ancient code constructs to standardized ones.
2507 Luckily, Lyndon Nerenberg focused on this task at the nmh project. 2665 Luckily, Lyndon Nerenberg focused on this task at the nmh project.
2508 He converted large parts of the code to POSIX constructs, removing 2666 He converted large parts of the code to POSIX constructs, removing
2509 the conditionals compilation for now standardized features. 2667 the conditionals compilation for now standardized features.
2510 I'm thankful for this task being solved. 2668 I'm thankful for this task being solved.
2511 I only pulled the changes into 2669 I only pulled the changes into mmh.
2512 mmh. 2670
2513 2671
2672
2673
2674 .H2 "Modularization
2675 .P
2676 The \fIMH library\fP
2677 .Fn libmh.a
2678 collects a bunch of standard functions that many of the MH tools need,
2679 like reading the profile or context files.
2680 This doesn't hurt the separation.
2681 .P
2682 whatnowproc
2514 2683
2515 2684
2516 2685
2517 .H2 "Separation 2686 .H2 "Separation
2518 2687
2519 .U2 "MH Directory Split 2688 .U3 "MH Directory Split
2520 .P 2689 .P
2521 In MH and nmh, a personal setup had consisted of two parts: 2690 In MH and nmh, a personal setup had consisted of two parts:
2522 The MH profile, named 2691 The MH profile, named
2523 .Fn \&.mh_profile 2692 .Fn \&.mh_profile
2524 and being located directly in the user's home directory. 2693 and being located directly in the user's home directory.
2616 de-facto is an improvement. 2785 de-facto is an improvement.
2617 However, the main achievement is the 2786 However, the main achievement is the
2618 split between mail storage and personal configuration files. 2787 split between mail storage and personal configuration files.
2619 2788
2620 2789
2621 .H2 "Modularization 2790
2622 .P
2623 whatnowproc
2624 .P
2625 The \fIMH library\fP
2626 .Fn libmh.a
2627 collects a bunch of standard functions that many of the MH tools need,
2628 like reading the profile or context files.
2629 This doesn't hurt the separation.
2630
2631
2632 .H2 "Style
2633 .P
2634 Code layout, goto, ...
2635
2636 .P
2637 anno rework
2638 2791
2639 2792
2640 2793
2641 2794
2642 .H1 "Concept Exploitation/Homogeneity 2795 .H1 "Concept Exploitation/Homogeneity