Comments for // I Have a Commenthttp://dn.codegear.com/article/208722008-11-19T08:01:41-08:00One example of how not to write comments?Dmitri Papichevhttp://threads.codegear.com/threads/threads.exe/userall?commentid=29989http://threads.codegear.com/threads/threads.exe/view?commentid=299892001-09-24T06:56:20-07:002001-09-24T06:56:20-07:00One example of how not to write comments?Robert, you give the following example in the article: if (x> y) or (not finished) then exit; //Exit if still calc and x > yIs that an example of how NOT to write comments? According to the known rule "No comments is better than wrong comments" :-)Note OR in the code and AND in the comment.I Have a CommentPeter Gummerhttp://threads.codegear.com/threads/threads.exe/userall?commentid=29909http://threads.codegear.com/threads/threads.exe/view?commentid=299092001-09-13T18:28:58-07:002001-09-13T18:28:58-07:00I Have a CommentI've only just read this article, although it's now 18 months old, but I just want to say I think it is excellent. The follow up comments expressed great sense too -- except for the guy who wanted gigantic routine headers.Robert's principle of "why not how" expresses beautifully what comments should be. It reminds me of Bertrand Meyer's advice in "Object Oriented Software Construction": when writing comments, assume that the reader is competent in the programming language.Another thing Meyer says in that book is, "Don't even think of writing a routine without a header comment!" But the header comments he wants are terse one-liners. I try to do this, although I often find the comment does little more than repeat the name of the routine!Special descriptions of the return values of functions should never be needed, because that is exactly what the function's header comment should be describing. Descriptions of arguments could be needed, but if they are important enough to be arguments then they are likewise probably best described as part of the description of the routine itself. Two other factors also come into play:1. Well designed OO software normally has very few routine arguments anyway, because one argument is implicit - the object itself - and many of the other arguuments that you would see in procedural code are "passed in" as part of the object itself: i.e. in its properties or field variables.2. If you adopt Meyer's idea of "Design by Contract" -- which in Delphi would mean that you do Assert calls on values of arguments at the beginning of the routine and on the result at the end of the routine -- then this in itself forms part of the comments for the routine. Programmers should learn to read these assertions as they would read a comment, to find out what the routine expects and what it returns. Calling Assert is like writing an execuable comment!re: I Have a CommentRobert Kozakhttp://threads.codegear.com/threads/threads.exe/userall?commentid=24383http://threads.codegear.com/threads/threads.exe/view?commentid=243832000-03-03T14:28:53-08:002000-03-03T14:28:53-08:00re: I Have a CommentPersonally, I think this is a little too much. Okay for a unit header comment but not for a routine. Remember you want to tell the why in a comment.o Project name and procedure name do not need to be repeated in a routine's comment.o Purpose should state the "why" of the routine.o Inputs and Outputs are known and should only be explained as needed.o Change history is really unecessary if you use a proper source code control tool. (And you should)re: I Have a CommentTrevor de Koekkoekhttp://threads.codegear.com/threads/threads.exe/userall?commentid=24380http://threads.codegear.com/threads/threads.exe/view?commentid=243802000-03-03T13:21:53-08:002000-03-03T13:21:53-08:00re: I Have a CommentIf you have procedures of large length, then chances are your code needs refactoring. This is one of the code "smells" in Fowler's book.re: I Have a CommentTrevor de Koekkoekhttp://threads.codegear.com/threads/threads.exe/userall?commentid=24379http://threads.codegear.com/threads/threads.exe/view?commentid=243792000-03-03T13:20:15-08:002000-03-03T13:20:15-08:00re: I Have a CommentLarge headers like this on top of functions usually become out of date. They also make the source code harder to read. I understand your desire for them, but personally I do not find them helpful but rather harmful.re: I Have a CommentAlisdair Meredithhttp://threads.codegear.com/threads/threads.exe/userall?commentid=24375http://threads.codegear.com/threads/threads.exe/view?commentid=243752000-03-03T08:18:28-08:002000-03-03T08:18:28-08:00re: I Have a CommentHow does this affect code legibilty?If you are writing procudures of reasonably length, it looks like you will quickly have more comments than code. I would find this far worse than the problem it is trying to cure.What we really need are smarter tools, where we can maintain this sort of information easily, and have ready access to it (show it inline in the code?) but also easily hide it when not relevant!The trouble with text files is they are not terribly context sensitive!re: I Have a CommentGerry pettipashttp://threads.codegear.com/threads/threads.exe/userall?commentid=24373http://threads.codegear.com/threads/threads.exe/view?commentid=243732000-03-03T07:15:50-08:002000-03-03T07:15:50-08:00re: I Have a CommentI always put a header on each function. The header describes the function, when it was created, who created it, who did revisions on the function and when and what was done. {*************************************************************** * * Procedure : Tfrm_MainConsole.FormCreate * Project Name: MyProject * Purpose : This procedure is called when... In this procedure, we will: - ... * Inputs : none (Sender) * Output : none * Author : Me * Created on : 01/01/2000 8:51:57 AM - Created by Me * History : 02/14/2000 9:27:12 PM - Change by Me * - Changed this... * 03/03/2000 12:15:05 AM - Change by Me * - Changed this... ****************************************************************}This helps to eliminate confusion as to the exact purpose of the function.re: You can learn good things from a book on FORTRAN ...Deepak Shenoyhttp://threads.codegear.com/threads/threads.exe/userall?commentid=24340http://threads.codegear.com/threads/threads.exe/view?commentid=243402000-02-29T06:56:48-08:002000-02-29T06:56:48-08:00re: You can learn good things from a book on FORTRAN ...There's this book I was reading - it's by Kernighan&Pike and the name of the book is "The practice of programming".Here's the link:http://www.amazon.com/exec/obidos/ASIN/020161586X/o/qid=951835669/sr=8-3/002-1804737-0429028I like the book for its explanations and it helps that the pseudocode is somewhat like Object Pascal. It's got a nice section on commenting - with code examples.One thing I picked up somewhere along the way was:1. When writing a function, write what you need to do in plain english. 2. put that into comments and if you like, intersperse it with code. Or, put it in a comment block above the function definition. Of course, repeated code changes tend to neutralize this if you don't remember to update the comments. What's important really is to name your variables right. re: I Have a CommentCraig Stuntzhttp://threads.codegear.com/threads/threads.exe/userall?commentid=24336http://threads.codegear.com/threads/threads.exe/view?commentid=243362000-02-28T11:26:16-08:002000-02-28T11:26:16-08:00re: I Have a CommentYes, Martin Fowler's book _Refactoring_ is a good one; I also had the same thought when I read the article on comments.In fact, I think that self-commenting code, such as appropriately named methods, deserves a mention of its own in an article on the proper use of comments.Also worth noting is the issue of "commenting out" suspect code. It's a legitimate debugging technique, but it should never be left in when the file is checked back into version control....or at least, not without a comment...re: You can learn good things from a book on FORTRAN ...Robert Kozakhttp://threads.codegear.com/threads/threads.exe/userall?commentid=24335http://threads.codegear.com/threads/threads.exe/view?commentid=243352000-02-28T11:26:07-08:002000-02-28T11:26:07-08:00re: You can learn good things from a book on FORTRAN ...Thanks for the link. Amazon doesn't have much to say about this title. Can you tell me a bit more about it?-- Robert Kozak (Borland)