What’s in a Comment?
16 April, 2007
There has been some talk recently around the Squeak / Seaside communities about putting comments in code. I thought I’d spend a few minutes talking about it.
Much has been said about Smalltalk being “self documenting”. This is mostly because those of us that can read object oriented programming are very used to seeing program flow, looking at senders of methods, checking other implementers, and generally perusing the class hierarchy. We flow and float through the code until there are so many windows all over the place that people walking up behind us, especially non OO programmers, are aghast.
They say something like how can you find anything in that mess of open windows? We all have our tricks; a little corner left here, a few stacked windows there, maybe a menu option or a button. Some are just like me: can’t find it, open another window, or just start closing everything till it comes up! Browser based development is really fun!
With all this mucking around in code it is pretty easy to believe that the code does document itself. It is also easy to believe that as you are opening and closing so many windows that there is no logical starting place for comments that makes sense.
I believe that these statements, the code is self documenting, and there is no good place to document in code, are wrong. Comments deliver two very basic benefits. First they give context to flow. Good comments can help to point you in the right direction. If you have a method that is protected by callers or has other considerations that may limit the usefulness of a method, you had better put a comment in. Otherwise you can be sure some other developer will use the method wrong and make the mistake you thought was obvious. Class comments are a very good example of this. Having a class comment that just points you to the default flow of the object can really help.
I know, I know you can accomplish this with method categories. I often have a protocol called: Start Here. Sure it is odd but it really helps to segregate your public interface and make it easier for developers to find. I’ve read up on programming by contract and the concept there is really very cool. Taken to its simplest implementation programming by contract benefits could be gained just be comments alone, noting context, usage and flow.
The second major benefit to comments is to clarify your intention. If you think a method does something and you put that something in your comment then later when it turns out that your assumption fails and incidentally is breaking something which is why you are reading the code in the first place, the comment gives you a warm fuzzy feeling inside that the situation you are seeing is a bug.
Are comments in code a good substitution for real documentation? No. Code comments can not take the place of real diagrams. They are not full explanations, or examples. Those things need to be done too. There are some tools whose goal is to help you build those software artifacts. I really love looking at the tools but I have yet to find anyone that says they really do what they say they will.
Software artifacts are just that, artifacts. Expect them to be old and covered in dust. Get out your brush and carefully remove the layers to expose what was. If they are kept up they are useful, but they can also be useful later even if they have rotted at the edges. Besides documentation clean-up is good work to give someone that has just started but nobody has had time to fully train yet. (oops, did I say that out loud).
All kidding aside the code comments are very useful, they are more likely to be maintained, and can really save a lot of development time later. They can help point you in the right direction, and if you are new to OO programming, having access to the author’s thoughts when the code was written is invaluable. Besides they can really make some funky code kinda make sense.
Write more comments!
Ron Teitelbaum is President and Principal Software Engineer at US Medical Record Specialists. He is also the Squeak Cryptography Team Leader, the Squeak News Team Leader and all around good guy!
The Weekly Squeak 
17 April, 2007 at 16:21
I come to Squeak via Croquet (a statement likely to be heard more and more, if the Little Gods of Computing have any sense) and the lack of comments in the core of Squeak as well as Croquet is just exasperating. Though I’m not a programmer but a Unix sysadmin I produce a lot of code, and I’ve always been a big fan of Lisp and have used Python for my work for years now. Documentation strings rock! I feel I could learn Smalltalk, Squeak and Croquet a lot more quickly if I had more guidance within the code about what any particular chunk is supposed to do, what problem exactly it solves, and how I’m supposed to use it. What little code I’ve started to write for myself in Croquet is highly chatty (in comparison to the norm), usually in class comments.
In its heart of hearts, Squeak wants to replace my desktop. I let it do so sometimes, but I could do that a lot more if I didn’t have to leave the environment to hunt down documentation about the system itself.
And that browser-based development is, I suspect, going to be a problem for a lot of people. The first time I encountered it months ago I was repelled and immediately deleted the Croquet SDK. I downloaded and deleted it a few more times before I finally left it in place. I’m still often appalled at the Squeak interface, but as a long-time emacs user I understand philosophically what it’s trying to do and why, which makes me a bit more tolerant of the interface if not exactly cheerful about it. I just wish I didn’t have to handle the mouse so often. I’m also used to seeing more of a class all together in one window. Whisker helps a little.
18 April, 2007 at 00:50
Ron said:
“I’ve read up on programming by contract and the concept there is really very cool. Taken to its simplest implementation programming by contract benefits could be gained just be comments alone, noting context, usage and flow.”
Implementing a Contract (a la, Design by Contract) for each class would be very beneficial and go a long way to documenting Squeak. Plus, a Contract Browser could be easily implemented, or integrated into the System Browser, so that viewing class contracts would be easy.
21 April, 2007 at 22:42
You can use Emacs to edit squeak code. There is FTP server interface for that. http://www.cincomsmalltalk.com/userblogs/avi/blogView?showComments=true&entry=3303394043
24 April, 2007 at 15:59
Comments in code take time to write (or rather to think). That time can only be spend once, and I do not feel that spending it on writing comments currently provides the most value/time in the seaside case.
24 April, 2007 at 16:32
Hi Stephan,
Comments are a philosophy they should become a habit. I can’t believe that the time it takes to write the comment can compare in any way to the time it takes to figure out and create the code. I may spend 10 min on a method. Writing the code, setting up a test, working through an example. The comment takes what 30 seconds, and doesn’t have to be debugged!
I agree not everything needs a comment. I just spent 15 minutes looking for Michel Bany’s email about resetAll! I kinda knew where to look for it but since it has all been redone some comments would have been nice. I even looked through the release comments to try to find it. That is really silly. We could really use comments on the changes to dispatcher, including a hint to use #resetAll.
I just saw that FileLibrary register was removed. My code registered my subclass. So it blew up when I was loading my code into a new image. There was a comment in there that said this was no longer needed I looked at senders and saw that it picked up subclasses. The comment saved me a good 10 minutes figuring it out. Thanks Philippe for the comment!!
-Ron
17 May, 2007 at 16:51
Or, the comments are the code.
See my essay/rant on this subject, which references Smalltalk, that I entitled “Thinking with Style, Writing Software Books”:
http://www.lanovaz.org/daniel/Shared%20Documents/Thinking%20with%20Style
or
http://tinyurl.com/3yrmpe
The article is also referenced from the Literate Programming website:
http://www.literateprogramming.com/tools.html
Daniel
23 May, 2007 at 07:16
I am an amateur coder, picking up this language here, that language there, and goodness knows how much other stuff everywhere else. I find comments practically invaluable, as I know so little proper programming.
The small amount of commenting in Squeak does have one positive effect though, it cuts down on the image size. These days, that’s not such a problem, but in days gone by when you needed every MB you could get, the amount of space an image took up could get awkward, and comments would only have made that worse. However I prefer comments. Maybe somebody could make TheAnnotatedSqueak.image. Then you could load that sucker up into Whisker and you’d have everything you needed. Kind of like The Annotated C++.
Interesting blog, by the way. If I ever work out how, I ought to pingback in my blog to yours.