Mercurial > docs > master
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 |