Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!mnetor!seismo!ll-xn!ames!ptsfa!nonvon!mc68020 From: mc68020@nonvon.UUCP (mc68020) Newsgroups: comp.lang.c Subject: Re: Writing readable code Message-ID: <598@nonvon.UUCP> Date: Mon, 6-Jul-87 21:39:19 EDT Article-I.D.: nonvon.598 Posted: Mon Jul 6 21:39:19 1987 Date-Received: Sat, 11-Jul-87 01:08:45 EDT Organization: NONVON Systems Computer Research Group Lines: 71 I have been reading all the articles in this series on readable code. I have seen some thouroughly ridiculous and outrageous comments and suggestions, fortunately more than outweighed by the rational, well though out comments of a few of our resident experts. What bothers me, however, is that while all of this discussion about style, readability and portability is educational and even, for the most part, enjoyable, I have seen not one mention of what I consider to be the single most important element of well written, portable code (in *ANY* language, not just C!). That element is DOCUMENTATION. COMMENTS. It is all well and good for the expert C guru to casually dismiss this with the most common (and most heinously WRONG) argument "any programmer good enough to work on this code should be able to figure out what it does." Sure, a good programmer needs to be able to analyze a piece of code. This does not by any means imply that *EVERY* piece of code written should enforce such analysis through lack of proper documentation. Such excuses are precisely that, the excuses or rationalizations of lazy, arrogant programmers. The plain fact of the matter is that any program that is undocumented is a poorly written program, I don't care *WHO* wrote it, how elegant the executable code is, how beautiful the algorithms...without documentation, the program is incomplete. As an example, there is a small C program included in the news 2.11 distribution, under the misc directory, named article.c. I will not name any names, but it was written by a very well known and highly respected member of the UNIX/net community. I am sure that the program does whatever it does elegantly and efficiently. Therein lies the rub: What the **** does the program do? No documentation header, no comments saying: this program does XYZ. There are a few scattered comments in the code which are virtually useless to anyone but a guru level programmer, and probably not of much value to them. This program should NOT have been included in the distribution. What for? So I can take several hours to several days of my time analyzing it to figure out what the **** it does????? Of course, in all fairness, it is almost as well documented as the news software itself. I *HATE* approaching the problem of porting some piece of code from mod.sources to my system, because in 98% of the cases, there is little or no documentation included. It is *WONDERFUL* that someone took the time to write a piece of useful code, and chose to share it with the rest of us. Commendations and kudos to the contributors! I should think, however, that they would be ashamed to place in the public domain incomplete, poorly written programs with THEIR names on them! (by that I am referring the above harped upon issue of undocumented programs being incomplete programs) Frankly, I see two major classes of people foisting this crap off on the world: those who are simply too lazy to do things correctly (probably far and away the largest group), and those whose arrogance causes them to deliberate obfuscate. Yes, I accuse many of the experts, particularly the older experts, of deliberately making their code difficult to read, and to understand. I believe their attitude is something like: "*I* had to suffere through poorly documented code, and no comments, so everyone else should too." I have had some experts say such things to me in so many words. I say to them, and to all of you, that such an attitude is anti-social, counter- productive, rude, and downright vicious. So far as I am concerned, if that is your attitude, then KEEP your damned knowledge, because it is flawed, just as you are flawed. My apologies for the long-widedness and slight flamage. This is an issue I take very personally.