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 
Leave a reply to dmitry Cancel reply