Xref: utzoo comp.software-eng:2576 comp.misc:7536 Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!ucbvax!hoptoad!tim From: tim@hoptoad.uucp (Tim Maroney) Newsgroups: comp.software-eng,comp.misc Subject: Re: Coding standards (was Re: Programmer productivity) Message-ID: <9157@hoptoad.uucp> Date: 1 Dec 89 22:48:48 GMT References: <34796@regenmeister.uucp> <2226@jato.Jpl.Nasa.Gov> <128179@sun.Eng.Sun.COM> <546@sagpd1.UUCP> <4727@netcom.UUCP> Reply-To: tim@hoptoad.UUCP (Tim Maroney) Organization: Eclectic Software, San Francisco Lines: 63 In article dopey@sun.UUCP (Can't ya tell by the name) writes: >I would set strict standards that deal with well written programs >(e.g. IMHO a. few if any globals, b. one routine per file, c. well >documented, etc.). In article <4727@netcom.UUCP> hue@netcom.UUCP (Jonathan Hue ) writes: >My $0.02: I don't agree with (b) at all. [...] >I think adhering to (b) would tempt you into writing >functions longer than you really should (Aw, I don't want to come up with >another filename for this 40 line chunk of code. I'll just shove it in >inline wherever I need it). > >At my last job we had a guy that adhered to (b) because he "didn't like >searching around to find out where a function was". [...] >Because of his strict adherence to (b), and his desire >to keep the number of files down, he would write 700 to 2000 line functions. I share your distaste for the rule of one routine per file. Short functions are almost always easier to read than long ones. A medium-sized project (say, 15,000 lines) with functions averaging out at a reasonable size (say, forty lines) would have 375 source files using this rule. What an atrocity! >Regarding (c), well documented to me doesn't necessarily mean lots of comments. Absolutely. Clear code shouldn't *need* a lot of comments; a programmer should be able to read it and understand what's going on from the routine names, the variable names, and the flow of control, with just a few added comments if any. A lot of extraneous comments about things that would be perfectly clear just from reading the code actually damages code readability; the control structures become much harder to follow. There are a lot of people who adhere to an rule that more comments are always better. I worked with a piece of code like that this year. I couldn't make heads or tails out of the commented version, which wound up a few hundreds of lines. So I sat down and ruthlessly stripped out all the comments, and when the code was reduced to a few tens of lines, I then reduced the control structures to the simpler forms which emerged when you could actually start to see the forest for the trees. After that, it became comprehensible. In summary: Clear code is far more important than extensive comments. >At one place I worked there were separate documents which described how >each subsystem of the product worked. The documents gave an overview, and >had separate sections for each of its parts which described what all the >functions did and how they worked. The comments in the code described anything >which wouldn't be obvious to someone who had read the documentation. Having >this type of documentation is extremely valuable when bring new people on >board. Much better than sitting down with 100K lines of code and going through >it with a new hire. 'Course, none of this ever gets written until the first >release goes out... Again, I agree. External documentation is very useful; far more so than most code comments. -- Tim Maroney, Mac Software Consultant, sun!hoptoad!tim, tim@toad.com "Every institution I've ever been associated with has tried to screw me." -- Stephen Wolfram Brought to you by Super Global Mega Corp .com