Path: utzoo!utgpu!news-server.csri.toronto.edu!rutgers!gatech!ncar!cgdisis.cgd.ucar.edu!gary From: gary@cgdisis.cgd.ucar.edu (Gary Strand) Newsgroups: comp.misc Subject: Re: MEL - A *Real* Programmer Message-ID: <9005@ncar.ucar.edu> Date: 31 Oct 90 05:07:51 GMT References: <1990Oct23.235720.16178@nas.nasa.gov> <6089@nisca.ircc.ohio-state.edu> <54296@brunix.UUCP> <5777@suned1.Nswses.Navy.MIL> <8187@gollum.twg.com> Sender: news@ncar.ucar.edu Reply-To: gary@isis.cgd.ucar.edu (Gary Strand) Distribution: usa Organization: Climate and Global Dynamics Division/NCAR, Boulder, CO Lines: 54 Disclaimer: No comment. > Dave W. Hamaker >> Gordon C Zaft >> The real solution, of course, is to make people write a program, then, 3 >> years later, have them revise it. For people that weren't around 3 years >> earlier, have them revise someone else's code. This will provide >> first-hand evidence of why one should write clear, well-commented code. > It has been my experience, on code I don't have to worry about others > having to maintain, that documenting each program on the assumption I > _will_ revisit it years hence (verses the cost of spending a little longer > reorienting myself on those I actually end up revisiting) seems to require > _more_ total time and effort. In short, your solution does not work for > me. It does for me. A case in point, I wrote a relatively trivial but tedious package in which keeping track of where you where geographically speaking was the most important thing. Also, since it ran on a CRAY X-MP/48 (that is, a 64-bit machine), if-tests were always done using the "difference less than sigma" fashion, since equality is a rarity when you're also trying to keep accuracy. I wrote it and documented it *fully* (I even made a nice hardcopy guide for it) during the summer of 1987. Jump forward three years to summer 1990. Boss wants me to dust off that old code and get it to work on a different initial data set. Boy, was I glad I had all that documentation. The Gary Strand and his style of 1987 are quite different from me and my style today. I was tempted to rewrite a bunch of the older stuff because it didn't match what I write now. Of course, that would very likely break what wasn't broken, and my boss did not want me to have to re-test and re-check everything, when he wanted results *now*. So, even if you and only you are the sole person to ever see that code (and have to maintain and/or use it) again, it's best to have plenty (of course, not excessive) documentation around, else you might be surprised at just how much you forgot and have to spend time retracking your ideas and then whack yourself on the head and say "Oh yeah, *now* I remember why I did that way!" when a little note could have saved all that heartache. Why add more variables to the equation than necessary? ["Overcommenting"] > Anyone else experienced this? Yes, of course. Now, if I was given a choice between "overcommenting" and "undercommenting", I'll take too much over too little every time. Yes, way too many comments are a drag, and it can be overdone, but I'd rather see 1 comment line for a trivial line of code than 1 comment for 200 (or even 20) lines of complicated mish-mash, which was so "obvious" when it was written, even if you're the one who originally wrote it. -- Gary Strand Look, it's trying to think. Internet: strandwg@ncar.ucar.edu Voicenet: (303) 497-1383