home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4954 < prev    next >
Encoding:
Text File  |  1992-12-14  |  1.9 KB  |  44 lines
  1. Newsgroups: comp.software-eng
  2. Path: sparky!uunet!zaphod.mps.ohio-state.edu!darwin.sura.net!max.fiu.edu!serss0!feathers
  3. From: feathers@serss0 (Michael Feathers)
  4. Subject: Re: C CODE LAyout
  5. Organization: Florida International University, Miami
  6. Date: Tue, 15 Dec 1992 00:35:40 GMT
  7. Message-ID: <Bz9yzH.M97@fiu.edu>
  8. References: <MARTINC.92Dec11214534@hatteras.cs.unc.edu> <1992Dec14.084405@eklektix.com> <MARTINC.92Dec14120615@hatteras.cs.unc.edu>
  9. Sender: news@fiu.edu (Usenet Administrator)
  10. Lines: 32
  11.  
  12. In article <MARTINC.92Dec14120615@hatteras.cs.unc.edu> 
  13. someone, ..  I_do_not_know _if_it_is_ martinc@hatteras.cs.unc.edu (Charles R. Martin) writes:
  14.  
  15. >   I don't see any objection to comments
  16. >   describing difficult points, unusual constructs, etc.--although I'm led to
  17. >   a feeling that I have, that the way to fix obscure code is to remove the
  18. >   obscurity, and that therefore commenting around it is an admission of
  19. >   defeat.  Better to comment than to leave it obscure and unexplained, of
  20. >   course!
  21. >
  22.  
  23. I am a firm believer in minimal commenting of code.  I try to write every
  24. method in a self-explanatory manner and I have a sure-fire way of discovering
  25. whether the meaning of the code is explicit enough to not require commenting:
  26.  
  27.    I reach into the next cubicle at work and grab a fellow programmer by
  28.    the lapels and ask him if he can understand what I'm doing with a 
  29.    cursory glance.  Since we work on different projects, I know that he
  30.    is not bringing background knowledge to the viewing.  I listen to what
  31.    he says that he does not understand and I listen what I am motivated to
  32.    tell him (anything that is non-obvious) then I document accordingly.
  33.  
  34.  
  35. Right now I feel that comments are only for learning what is not obvious in the
  36. code, and that comments can never be a substitute for reading the code when
  37. learning a system.  In spite of this, I'd like to try a web system sometime
  38. if one is developed for C++.
  39.  
  40. feathers@fiu.edu
  41.  
  42.  
  43.  
  44.