Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!cornell!rochester!rutgers!att!ihlpb!nevin1 From: nevin1@ihlpb.ATT.COM (Liber) Newsgroups: comp.software-eng Subject: Re: comments on comments Keywords: comments Message-ID: <9606@ihlpb.ATT.COM> Date: 16 Feb 89 00:54:23 GMT References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> Reply-To: nevin1@ihlpb.UUCP (Nevin ":-)" Liber) Organization: AT&T Bell Laboratories - Naperville, Illinois Lines: 124 In article <4173bd76.183dc@apollo.COM> perry@capsicum.UUCP (Jim Perry) writes: >Let me begin by saying that I'm in the camp calling for more comments. I'm not. I do agree with you on the problem (poor documentation), but I do not think that more comments is the answer. >Especially in the Unix/C world, the overwhelmingly vast majority of >programs are undercommented. It's interesting that some aspects of >programming style, e.g. indentation, are fairly consistently applied, >while adequate documentation is the remote exception. The question is: Why? From my point of view, good documentation in the form of comments is rare because there is NO WAY of guaranteeing that they are correct with respect to the code. They are a nightmare to maintain, and no one ever has the time to fix the comments when the code has fatal bugs. Also, no one wants to take the time to rewrite their code into English; it's a boring, tedious job, and when it comes down to it only the code really matters to those buying your software. It is human nature to take the path of least resistance; comments go against this path. With very few exceptions, for better or for worse, this is the way of the world. Will requiring Joe Programmer to write more comments fix the situation? No. Joe Programmer will find a way to keep his comment writing to a minimum, even if the code or organization of modules has to suffer for it. >C crams so much stuff into >a small area that just expressing what's going on, in English, would >generate huge comments. I consider this very fact an argument for the >programmer taking the time to construct a pithy description of what a piece >of code is intended to do. And I do, by and large, comment every line. Suppose you require Joe Programmer to comment every line of his C code. What does Joe Programmer do? He writes: (void)strcpy(string0, string1); (void)strcat(string2, string3); (void)strcat(string0, string2); as (void)strcat(strcpy(string1, string0), strcat(string2, string3)); because he only has to comment one line instead of three. The code is less readable in case 2, but Joe Programmer has achieved your goal (a comment on every line) with less effort. (Note: the opposite problem is true when you are measuring number of lines of code as a quality measure: Joe Programmer might rewrite line one of the first case as ( void ) strcpy ( string0 , string1 ) ; and make a tenfold improvement in his statistics!) Here are some real-world examples of what happens when you force a programmer to write lots of comments: Requirement: require file comments in each source file. What Happens: Many functions are stuffed into a single source file, irregardless of whether the functions are related or not. Requirement: require block comments for each function declaration. What Happens: Functions become less modular. In C, a programmer might stuff five functions into one by using a giant case statement. Requirement: always provide a list of what a given function calls and is called by. What Happens: These comments are out of sync very fast. This kind of documentation is much better handled by a software tool than by a programmer. Unfortunately, I have seen the What Happens all too often. Forcing programmers to write more comments is not the answer. What is? >Code should be self-documenting, at all levels. The main body of a program >should explain what the program does, what the dependencies, files, etc. >are, and so on. The data declarations should explain what the data >structures are and how they are used. Functions, modules, procedures, >macros, etc. should also explain themselves, and so on. This is the solution: code should be self-documenting. But, self-documenting is not the same as commenting! When I change a line of code, my documentation should reflect that change automagically. I don't get this with comments, and because of it, the only comments I rely on are my own personal ones. What is needed to improve self-documentation are better programming languages. This is one of the reasons that, for example, C++ is better than C; the resulting code is more self-documenting. The language has to make it easier for me to abstract and be more self-documenting than not; this is the key to solving the problem. The ultimate programming language(tm :-)) will be one where I will never have to write a single comment; it should be clear, concise, and obvious from the code my intentions of what I was programming. We need to improve our programming languages, not increase the quantity of our commenting. >I've seen some >poorly though verbosely documented ones, as discussed here and elsewhere >not all programmers have great communication skills, but never has this >been "worse than nothing". There are many instances on where poorly documented code is "worse than nothing"; most notably, when the comments are WRONG! It has happened too many times that someone reads the comments on how the routine is "supposed to" work, makes a change, and finds out that the implementation is totally different than the comments. I wonder how many lost man-years in software maintenance can be attributed to this. -- _ __ NEVIN ":-)" LIBER nevin1@ihlpb.ATT.COM (312) 979-4751 IH 4F-410 ' ) ) "I will not be pushed, filed, stamped, indexed, / / _ , __o ____ briefed, debriefed or numbered! My life is my own!" / (_