From: utzoo!decvax!harpo!npois!cbosg!cbosgd!mark Newsgroups: net.misc Title: Re: Self-documenting code???? Shesh! Article-I.D.: cbosgd.2356 Posted: Mon Jun 14 10:10:45 1982 Received: Tue Jun 15 05:41:13 1982 References: sdcsvax.2093 While it is certainly important to be able to read code, comments are still crucial in programs of any size. In practice, of course, most programs are quite large. When a change needs to be made, it's most often a trivial change of a few lines. The problem facing the person who must make the change (usually not the author) is FINDING those few lines that need to be changed. Also, this person must figure out enough of the conventions used in the program to be able to make the change. There are two ways to get this information out of the program: (1) Read and understand the code. Most of it is irrelavent, but must be read and understood to determine that it can be ignored. (2) Read the comments. Good, high level comments at the front of programs, modules, procedures, and chunks of code are much faster to read than code, and make it faster and easier to find the appropriate place in the code. Of course, if the program fits on your CRT screen or on a page of line printer output, it may be as fast to read the code as to read the comments. But how many programs are this simple? The real problems are with the huge software systems that nobody knows every line of code.