home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4893 < prev    next >
Encoding:
Text File  |  1992-12-11  |  2.5 KB  |  62 lines
  1. Path: sparky!uunet!gatech!concert!borg!news_server!martinc
  2. From: martinc@hatteras.cs.unc.edu (Charles R. Martin)
  3. Newsgroups: comp.software-eng
  4. Subject: Re: C CODE LAyout
  5. Message-ID: <MARTINC.92Dec11214534@hatteras.cs.unc.edu>
  6. Date: 12 Dec 92 02:45:34 GMT
  7. References: <1992Dec11.020200.944@seq.uncwil.edu>
  8. Sender: news@cs.unc.edu
  9. Organization: UNC Department of Computer Science
  10. Lines: 49
  11. In-reply-to: herbst@seq.uncwil.edu's message of 11 Dec 92 02:02:00 GMT
  12.  
  13. In article <1992Dec11.020200.944@seq.uncwil.edu> herbst@seq.uncwil.edu (R.T. Herbst) writes:
  14.  
  15.    On the subject of C CODE layout.
  16.     ....
  17.     /*Declare external variables, functions, defines, and includes.
  18.    Use comments as necessary to describe variables.
  19.    */
  20.    main()
  21.    {
  22.    /*Declare internal variables*/
  23.  
  24.    /* Execute*/
  25.    }
  26.  
  27.    I like a format that leaves the code free from clutter.
  28.    The code in K&R has about the rigth level of commenting.
  29.    A good makefile will provide the relationship of main
  30.    program and related files.
  31.  
  32. I don't know that I mean to start a style flame war, but (as one of
  33. those people who had painfully to learn to write code with an
  34. unprofessional lack of comments in order to keep from losing points for
  35. "too many" comments in academic programming classes) I couldn't bear to
  36. let this go unchallenged.  
  37.  
  38. If I read it aright, Herbst "likes a format that leaves the code free of
  39. clutter" and therefore prefers to limit in-code comments to only those
  40. few setting off the sections, plus some comments on the general meaning
  41. of the code.
  42.  
  43. I frankly have always found it very difficult to believe that anyone who
  44. suggests such a style has any professional software engineering
  45. experience.  My experience has *always* been that, on examination, the
  46. people who discourage detailed comments in code have spent their entire
  47. professional career in academic settings, writing code in a small group,
  48. with relatively little maintenance of code by anyone other than the
  49. author, and in general with products of only a few thousand lines of
  50. code.
  51.  
  52. In the more common engineering environment, in which code must be
  53. expected to have a lifespan of several generations of programmers,
  54. *much* more detailed code commenting is not just desirable, it is
  55. essential. 
  56. --
  57.         Charles R. Martin/(Charlie)/martinc@cs.unc.edu
  58.      Dept. of Computer Science/CB #3175 UNC-CH/Chapel Hill, NC 27599-3175
  59.         3611 University Dr #13M/Durham, NC 27707/(919) 419 1754
  60.      "Oh God, please help me be civil in tongue, pure in thought, and able
  61.       to resist the temptation to laugh uncontrollably.  Amen." -- Rob T
  62.