From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=0.1 required=5.0 tests=BAYES_05,INVALID_MSGID autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 109fba,f292779560fb8442 X-Google-Attributes: gid109fba,public X-Google-Thread: 10db24,30e368bdb3310fe5 X-Google-Attributes: gid10db24,public X-Google-Thread: f8c65,30e368bdb3310fe5 X-Google-Attributes: gidf8c65,public X-Google-Thread: 1014db,30e368bdb3310fe5 X-Google-Attributes: gid1014db,public X-Google-Thread: fac41,af40e09e753872c X-Google-Attributes: gidfac41,public X-Google-Thread: 103376,30e368bdb3310fe5 X-Google-Attributes: gid103376,public X-Google-Thread: 1008e3,30e368bdb3310fe5 X-Google-Attributes: gid1008e3,public From: clc5q@mamba.cs.Virginia.EDU (Clark L. Coleman) Subject: The Last Word on Comments (was Re: Hungarian notation) Date: 1996/05/31 Message-ID: #1/1 X-Deja-AN: 157751532 sender: usenet@murdoch.acc.Virginia.EDU x-nntp-posting-host: mamba-fo.cs.virginia.edu references: <4o07o9$rfu@seagoon.newcastle.edu.au> <4o1vo3$p2a@news1.ni.net> <4oegks$ntn@goanna.cs.rmit.EDU.AU> organization: University of Virginia Computer Science Department newsgroups: comp.lang.ada,comp.lang.c++,comp.lang.c,comp.lang.modula3,comp.lang.modula2,comp.edu,comp.lang.eiffel Date: 1996-05-31T00:00:00+00:00 List-Id: In article <4oegks$ntn@goanna.cs.rmit.EDU.AU> ok@goanna.cs.rmit.EDU.AU (Richard A. O'Keefe) writes: >andyc@procom.com (Andy Ho-Fan Chan) writes: > > >>Well, comment is important, but in academic, most of the time no >>one wants to do that. > >The smart ones do. >The smart ones know that you should always write the comments FIRST, >explaining your major data structures and how they work, >explaining the key ideas behind algorithms, >and you only start writing code after the comments look right. Finally, someone gets the point in this stupid discussion. Bravo to the professor from RMIT. Everyone else in the discussion is apparently so ignorant of how to design real-world software that their arguments are pathetic, ESPECIALLY those who claim to be working in industry and who are taking potshots at the "ivory tower" requirements for comments. Has anyone here heard of stepwise refinement? When you design and implement a system of hundreds of modules and hundreds of thousands of lines of code, you do not write a design description document and then start coding. You write a system requirements specification, then a system design (outlining decomposition into subsystems and the interactions between subsystems,) then subsystem design documents (breaking down each subsystem into modules (and classes, for OOP)), then module design documents for each module. The module design document has pseudo-code, among other things. A good software engineering environment will have a tool that extracts the pseudo-code from a file and makes the module design document out of it. Then, the code is added to the same file, interspersed with the pseudo-code comments, and the code is formally reviewed (as were each of the above documents.) 99% of the postings in this thread have assumed that the code exists, so how many comments should I add to it later? I have 15 years industrial software engineering experience on a variety of projects in a variety of software engineering environments at 4 companies. The people who claim to be from industry and have posted on this subject have been really disappointing. I shudder to think that someone is paying them to develop code if they really think you add comments after the code is written. Whether you do object-oriented design (as I am currently doing in industry), or functional or logic or imperative programming, you are going to use stepwise refinement to move from requirements down to code. As I indicated above, the number of conceptual levels is 4 or 5 for a big project. The level that immediately precedes the coding will require pseudo-code, which should remain imbedded in the final code, not thrown away. Among the amazingly bogus statements made in this discussion was the declaration that any comment indicates that your language was not expressive enough, and hence you would ideally have no comments. This is surely the most ignorant statement ever made about the subject. If you have not worked on truly large projects that were proven to be maintainable by others after you were finished; if you have not worked on dozens of software engineers / hundreds of thousands of lines of code projects; if you don't understand what "stepwise refinement" really means; if you think programming consists of sketching out an algorithm on a sheet of paper and then coding; PLEASE do not waste net bandwidth replying to this message. Get an education and some real experience first. The real problem in academia in this regard is the continual assignment of projects that will only take 1 to 3 pages of final source code. The number of levels of abstraction required in the design process is so few compared to industrial practice that students will incorrectly think that you spend little time designing before coding, which will not be true in general. -- -------------------------------------------------------------------------- "I have prevented my kids from watching MTV at home. It's not safe for kids." ---- Tom Freston, MTV president, 4/14/95 Buffalo News. ||| clc5q@virginia.edu (Clark L. Coleman)