Lambda the Ultimate

Back in the days when I did Mac development (System 6) the biggest monitors available for the Mac were maybe 9", and the only way to see a reasonable amount of code on screen was to use a tiny font. Now that I have two 18" LCD panels, the only way to see a reasonable amount of code on screen is to use a tiny font.

This quote is obviously a bit of tongue-n-cheek, but it does point to a tendency I've seen in many developers: a desire to view as much code as possible on the screen simultaneously.

It's obvious that the programming language you use, and the way you use it, impacts the amount of code you need to view simultaneously. So how much is/should be just right?

A common theme seems to be that succinctness is considered better than verbosity. Yet the succinctness used by some PLs results in unreadable code (Perl, APL - flame away), while some PLs are verbose by design (COBOL).

In addition modularization/componentization should lead to more compact code chunks. Yet if you often find yourself using a split view to see both function call and function implementation, you are worse of than before.

Finally, comments in code result in expanding the breadth of the code, yet everybody agrees the code comments are a good thing ...

Finally, comments in code result in expanding the breadth of the code, yet everybody agrees the code comments are a good thing ...

I use the smallest font possible on my stuff, but my eyesight was recently tested @20-15, so I don't have to squint like others. Still, I wish I could have more than 1 monitor while I'm coding/reading. The size of the monitor should be a full wall since I do lot's of drawing (ER/UML/etc... type diagramming). Wish I had the plotters that we used to have for drawing electronic schematics - they could handle 5 feet wide and even longer in length.

Another idea is filters, which we use in our project - they are preset constraints on what elements to show and what to hide, applied at one stroke throughout the document.

For those of us, who use graphical syntaxes, level-of-detail (LOD) is feasible. You scroll your mouse wheel, the viewport changes its zoom, the appropriate elements appear. This way you can have both a bird-eye view and a low-level high-detail view at your fingertips. Combined with filters, LOD practically obsoletes all other views except the main editor pane - everything is there, just play the right chord :-)

While this is also obviously written as tongue-in-cheek, I just had to state that I disagree. Example:

/*
 * Documentation template v.2.94
 * _____________________________
 *
 * Function name: transmogrify
 *
 * Purpose: transmogrify a widget into a gadget
 *
 * Arguments:
 *    - Widget widget (this is a user-supplied widget)
 *
 * Returns: a Gadget resulting from the transmogrify operation
 *
 * Error codes:
 *
 * Exceptions:
 *
 * Other notes:
 *
 * Author:
 *     Joe Luser - original version, May 17, 1987
 *     Earthworm Jim - fixed error as discussed with Peter, May 22
 *     Emanuel Desperados - complete rewrite for foobar, Sep 22, 1993
 *     ....
 */
Gadget *transmogrify(Widget *w)
{
   /* This will serve as our return value */
   Gadget *gadget = new Gadget();
   Policy policy = w->getPolicy(); // Return policy of widget!
   /* NB: this code is changed by Paul */
   bool neutral = false;
   if (policy == POLICY_SWISS)
       neutral = true; // set neutral since we are swiss!
   /* NB: Paul is finished for now */
   ____
   ...and so on for 1412 lines...
   ____
   return gadget;
}

At my previous company, we had tons of code like this. A commercial package to come up with code-metrics of various sorts essentially concluded that the code was unmaintainable, in large based on the number of comments....

The only worse type of commenting scheme I've encountered is when people comment out code sections that become obsolete, instead of just deleting them. I guess some developers worry that they may not fully comprehend the purpose of the code, and so may have to restore it later on. Even if that is the case, we have VCS don't we? I once spent an hour trying to decipher the convoluted initialization process of a variable, only to discover that all its uses have been commented out.

But to bring this discussion into LtU context, my initial intention was to try and determine how the PL you choose affects the amount of code you need to see simultaneously. Can Haskell developers get along with screen a quarter in size as Java developers? Is there an optimum size, e.g. if I maintain that a C++ function should not exceed, say, 60 lines, that may be the optimum size for that PL. The screen size becomes a very powerful tool for abstraction.

how the PL you choose affects the amount of code
It affects the shape of the code. Languages that restrict expression complexity, languages where subprograms use var/out parameters to return values, tend to be long and narrow.

A common belief is (or used to be) if you comment what each parameter "means" then the API can be used. But even when I look at javadocs, I look for sample code.

Comments in Smalltalk code often provide an example use. These are best when they can be selected and run using the "doit" menu. Also a system with source like Smalltalk allows you to find all senders of some message.

Even better these days, more and more people are writing unit tests that provide more than just a single example, and that can all be executed automatically with little setup.

The only advantage I can see for a comment like that is if it's read by an automated documentation facility like javadoc.

Sure, there was an awk script to do that. But what do you need it for? Looking at 10-15 year old javadoc that has a only a vague resemblance to the code as it exists today is not very useful. With that much commenting, you can't expect anyone to keep it up to date.

...is when people comment out code sections that become obsolete, instead of just deleting them.

How could I forget that one? Not to mention the vague "this may not work correctly"-comment that's been there for 15 years, and nobody even remembers what could go wrong. After days of investigation, it turns out the comment was either right or wrong, but wouldn't it be smarter to just tell what could go wrong? (or just fix it?). And instead of having code commented out, it's also pretty safe to just not call that function anywhere.

Is there an optimum size, e.g. if I maintain that a C++ function should not exceed, say, 60 lines, that may be the optimum size for that PL. The screen size becomes a very powerful tool for abstraction.

Well, it works good enough if it can be cited as common wisdom to be slammed in the face of somebody violating it. I doubt it automatically results in good design, but can certainly be an aid in detecting bad ones...

A common belief is (or used to be) if you comment what each parameter "means" then the API can be used.

I'd be interested in seeing what people perceive as useful comments. I used to believe in lots of comments myself, but have gotten much less fond of it lately.

Javadoc is clearly not very useful. Even in Java, it results in a lot of duplication of obvious info, and rather verbose code.

Documenting the purpose of a function is seldom useful, it should be evident from it's name, and source-file. Documenting an algorithm is seldom useful, algorithms are either obvious, or badly written (in real programs anyway, might be different if you are really doing something tricky). But a literature reference, or external paper is usually better than comments in this case.

Documenting code line-by-line is only useful for assembler (if even then). Documenting code per block, usually means each block should have been a function. Documenting preconditions, postconditions, and invariants is only useful if you have a tool to check them (which you don't have, or they wouldn't be comments). Having the version control system adding version history as a block comment at the top obscures diffs between different versions (unless the system strips them automatically).

In short, I've ended up with a view that comments should only express things that are not obvious. This is perhaps obvious to some, but for me it has caused me to realize that 99.99% of all comments are worthlessm because they only express obvious things.

And thus, for me, comments have become limited to a block comment at the top of each file, explaining purpose and overall organization (which basically means dataflow) (but only if it's not obvious), and whatever in-development comments, such as FIXME, that should be removed before anyone else sees the code anyway. And maybe a few data-structures, if they are particulary hairy...

What do you think is useful to comment?

I don't think any action can automatically result in good design. I do think some actions can assist in that direction, or at least as you've stated, aid in detecting bad ones.

I think a rule like "a function should not exceed screen size" can be a useful aid in that:

1. It's a very simple rule to understand.
2. It's easy verify.
3. Even people who don't grasp the benefits of modularization, or tend to neglect them, immediately understand the upside of being able to view all the relevant code at once.

I am so glad you mentioned this. To my mind, the value of unit tests as example code doesn't get talked about as much as it should. Well-written unit tests are a great source of examples of both good and bad uses, expected and (at least initially) unexpected uses, normal cases vs. boundary cases, and so on. And, compared to comments, it's a lot harder for unit tests to get out of sync with the good.

I disagree with this statement. I would've been okay with it if you'd said, "Javadoc is clearly flawed," but it is in fact clearly useful - thousands of developers make extensive use of the standard Javadocs every day. They do serve an important purpose.

Documenting preconditions, postconditions, and invariants is only useful if you have a tool to check them (which you don't have, or they wouldn't be comments).

Really? How can someone be expected to use your function without knowing its preconditions and postconditions? I find this a strange position to take. Certainly, having a tool/language feature to verify contracts is a good goal, but even if you don't have such a tool, contracts are still necessary.

Having the version control system adding version history as a block comment at the top obscures diffs between different versions (unless the system strips them automatically).

Couldn't agree with you more - yuck!

In short, I've ended up with a view that comments should only express things that are not obvious. This is perhaps obvious to some, but for me it has caused me to realize that 99.99% of all comments are worthlessm because they only express obvious things.

What it comes down to is that we would like our languages to be able to express as much of the information that we ourselves know (or want to know) about our programs, and to be able to verify these properties as well. (Better, we'd love for them to infer as many of the properties as possible.) Naturally, this is a hard problem, and comments serve to fill in the gaps of those things that we don't yet know how to capture (or more cynically, that the language designer didn't know how to capture). But just because you couldn't express it in the language itself doesn't mean it isn't useful.

One mathematician was showing his new theorem to another. The colleague pointed at the chalkboard and asked how the theorem went from one step to the next. The first mathematician said, "That's obvious." The second went to a second blackboard, spent an hour filling it up with complex calculations, then stepped back and said, "You're right, it IS obvious."

Obviousness is obviously relative. My experience has been that if I comment everything I had to think hard about, then two years later when I look at it again, I don't have to think so hard. And some maintenance programmer someday might appreciate it.

Javadoc and friends really are a waste of time, I think. I despair when I see that the documentation for a library with 241 interfaces has been autogenerated in JavaDoc -- (non-trivial and non-pathological) unit tests (with comments!) are much better.

Yes, I actually thought about that one while writing, thus my overuse of the word :-) Deciding what's obvious and not is certainly not obvious. And things you thought hard about is generally worth documenting. But my experience with reading code pretty much says that people tend to comment the obvious, and not the things they had to think hard about.

What javadoc gives you, is a simple way to write the equivalent of a unix man page, but for source code. Manpages are great for people who already know what something is supposed to do, and need detailed info. They are generally useless for getting an overview. As documentation of source code, this format is even more useless, since most of the time, the same information can easily be guessed from signatures/prototypes/definitions/whatever they are called in your language, and therefore isn't even useful for experts. What's needed is the what's why's and how's, a high-altitude overview, so you can start hacking the source.

A similar way to generate "work", but not really create anything useful is to document everything with static class diagrams, e.g. in UML. While these can be useful, they are also pretty easy to write, even with no understanding, just by glancing at the source, or even using an automated tool to do so. To actually understand something, you need to know the problem it is intended to solve, the solution method used, the general ideas of how this solution is expressed in the given language, and maybe interaction and dataflow (not necessarily as diagrams). As obvious as this seems to be to me, I have almost never encountered this documented in real life.

Ok, I might have overstated things a bit. Javadoc can also be useful. The documentation of JDK is actually useful, perhaps even twice as fast to look stuff up in, than from the actual source code. But for most stuff, you don't want to put in that kind of effort for such a small gain. A few lines of 10000ft overview is worth days of digging, especially for good designs that usually do something smart and non-obvious. Preconditions/postconditions/invariants can also be useful, but how often do you see something as complex that it cannot immediately be guessed? If it really is non-obvious, sure, go ahead and document it, but being anal about documenting every one of them, isn't going to help anyone, unless they can be automatically checked.

And finally, I must thank Patrick for the unit-tests tip too. I've never really thought about them as documentation, but they truly are the best kind in many situations... Yet another reason unit tests are good!