Xref: utzoo comp.software-eng:2612 comp.misc:7585 Path: utzoo!utgpu!jarvis.csri.toronto.edu!cs.utexas.edu!tut.cis.ohio-state.edu!rutgers!att!watmath!watmsg!sccowan From: sccowan@watmsg.waterloo.edu (S. Crispin Cowan) Newsgroups: comp.software-eng,comp.misc Subject: Re: Coding standards (was Re: Programmer productivity) Message-ID: <32359@watmath.waterloo.edu> Date: 6 Dec 89 05:36:37 GMT References: <34796@regenmeister.uucp> <2226@jato.Jpl.Nasa.Gov> <128179@sun.Eng.Sun.COM> <546@sagpd1.UUCP> <4727@netcom.UUCP> <9157@hoptoad.uucp> <473ae701.20b6d@apollo.HP.COM> <1989Dec4.222725.5920@athena.mit.e <1989Dec5.1 Sender: daemon@watmath.waterloo.edu Reply-To: sccowan@watmsg.waterloo.edu (S. Crispin Cowan) Organization: U. of Waterloo, Ontario Lines: 35 In article <1989Dec5.115934.24535@twwells.com> bill@twwells.com (T. William Wells) writes: >du> >Organization: None, Ft. Lauderdale, FL >Lines: 31 >Xref: watmath comp.software-eng:2636 comp.misc:7659 > >I'll add my two cents about commenting. I am a big fan of >*useful* comments. And I despise over-commenting. The latter is >any comment that is not the former. I don't understand the problem with over-commenting. First of all, it is _very_ rare (both :-) and :-(), and secondly, just skip it if it bugs you. >I have three simple rules: [good list of three rules] I also like to see ALL variables described. I can figure out what a for-loop is doing, but it's not at all obvious what the trans_rec_count variable is a count of (total transactions, to-date, how many gropple-grommits in this shipment, etc.). Unless it's just a scratch counter such as `i', it should be commented. >Bill { uunet | novavax | ankh | sunvice } !twwells!bill >bill@twwells.com ---------------------------------------------------------------------- (S.) Crispin Cowan, CS grad student, University of Waterloo Office: DC3548 x3934 Home phone: 570-2517 Post Awful: 60 Overlea Drive, Kitchener, N2M 1T1 UUCP: watmath!watmsg!sccowan Domain: sccowan@watmsg.waterloo.edu "The most important question when any new computer architecture is introduced is `So what?'" -someone on comp.arch (if it was you, let me know & I'll credit it)