Lambda the Ultimate

If anyone is interested in code reading workshop for his team etc., I am available (especially if you are in Israel, or when I visit your country) . Worhshops can be based on material you provide (i.e., code walks for subtle parts of your company's framework) or chosen by me per you specification. A representative from the client needs coordinate the session(s), and help tailor the workshop content.

Hands-on workshops that include exercises in code maintanence are also possible to arrange.

For more details, if you are interested, contact me by email.

I find reading almost any program using lots of classes (shallow or deep) difficult to read.

This is especially the case for languages that allow you to arbitrarily override method definitions. When I am perusing a derived class, I need to have a "mental image" of the parent class in order to see what methods "shine through" to the derived class and which are overridden. This can be maddening (especially when dealing with multiple inheritence or deep hierarchies).

I think that Eiffel requires you to specify that your are overriding a function by using a "redefine" keyword. That could certainly help. Also, ISE's Eiffel IDE allows you to "flatten" the structure of a class so you can see all of the inherited attributes/functions in one place. But that is an IDE feature...

A common Java problem: Given a dozen directories full of dozens (or hundreds!) of class/interface definitions (each in its own file), where do you start reading and how do you navigate?

I find that the best way to explain this (obvious) phenomenon to people is to make them realize the inheritance introduces coupling. People know coupling is problematic. Now let them draw their own conclusion about inheritance.

where do you start reading and how do you navigate?

That's a good question. Each programmer has his own tricks and tips. What are yours (tool suggestions are acceptable)?

For Java, my answer would be to go look at the automatically generated documentation (Javadoc or whatever). Same for .Net, in fact, or any of the Python standard libraries. If you can browse the code at an interface level, with comments on each of the methods and hyperlinks to the docs for other classes that are referenced in their signatures, then you can start to build up a picture of the code that way. Then you jump in to specific modules to look at the implementation.

These are useful (and semi language related), but not enough. If the system is large, you need to know where to start looking, even if you are only reading the documented interfaces - there's are simply too many of them.

Sure - but then the problems when things get large are problems outside of OO as well, I think. At the point I'd be looking for some human-generated documentation for orientation. One of the (desirable) consequences of modularised code, regardless of whether OO methods are involved, is that you can't infer the rest of the program universe just by looking at one piece of it (I'm thinking of Adams' Total Perspective Vortex here, obviously). So if you want to know where to start, something other than the bit of code you're looking at right now has to tell you.

I think that Javadoc et al do a reasonable job of making the connections between local clusters of classes visible, so they go some way towards remedying the fragmentation caused by breaking the code up into separate classes in separate files in the first place. But they won't give you the big, big picture - just information about how the pieces of a given module or library fit together.

Personally I prefer to be able to put multiple class definitions together in the same file, as you can in Python and C#. But you could equally well put multiple one-file-per-class class definitions together in the same folder; and there's no reason why an IDE shouldn't be able to knit the contents of a single folder together into one continuous text field for reading and editing.

It's low-tech, but I usually start with something along the lines of

find . -name '*.java' -print | xargs fgrep 'main('

to find the entry point(s), and then start doing a kind of depth-first search (usually just down the happy-path at first) through the code, via a combination of Javadoc and code browsing. It's been a while since my Java days, but I think I remember this being a productive approach.

But, I don't trust documentation--it's not the code. It's (at best) what "cliff notes" are to literature... Plus, documentation may (horrors!) not be updated when the code changes.

Someone once told me (Jim Coplien?): Trust the terrain, not the map.

i once used this plus a perl script to replace every occurence of an identfier with a link to its definition. that helped browse code (i was starting at a company with a lot of undocumented c code). i'm sure there are tools that do the same these days (maybe doxygen does this? http://www.stack.nl/~dimitri/doxygen/index.html)

Oh, so you reimplemented metapoint.

find . -name "*.java" | xargs wc -l | sort -n

What I like is a small number of directories, each with a small number of files, each of which does something significant. The files should have names that indicate what they do, plus a one-line comment at the top spelling it out. That one-line "Purpose" comment is the most important thing! This seems to generally be how C, Lisp, and Erlang programmers do things.

I guess Smalltalkers have a totally different point of view, because they have their standard Browser. Perhaps Java programmers work like this too nowadays, and their sourcecode layout is just annoying from a Unix-centric viewpoint.

When I really can't tell which way is up, I teleport.

Who else gets a warm and fuzzy feeling when they pull up a source file and see page-break characters in it? :-)

My latest habbit is that, when I want to know how some program on my computer works, I do apt-get source name-of-package and ten seconds later I have the source. I'm really impressed at how easy it usually is to find what I'm looking for in the source to popular (e.g. GNU) programs.

Then came Knuth's TeX and Metafont. I find Literate Programmers a bear to maintain (funky mark up) but a pleasure to read.

I've always printed out my own programs for offline reads. I find so much more inconsistencies, unused variables and poor naming in my code through printed perusal than online browsing.

I also like this trick. It's easy, doesn't require fancy tools, and often the most effective technique.

I agree. Drawing arrows with a red pen is also very helpful for figuring things out (especially if you can take points off, whenever the coding style annoys you...)

Every once in a while I print out and read the source to AFT. It consists of hobby-time coding over a period of 7 years. It certainly doesn't represent my ideal approach to programming (and I am not a Perl guru), but I can see spots where I improved my Perl coding, got into the rhythm of a particular technique and got hopelessly confused on how to properly use regular expressions.

Is the code maintainable? I think so. Its overall structure captures how features can be added through function dispatching and how global (blech) state is accessed.

Sure, I cringe sometimes at the darker corners of the code, but the overall structure is sound (although not ideal). The interesting bit about all of this (the reason why I bother mentioning my own crufty code), is that I still need to see the "whole picture" every once in a while in order to understand how to keep my localized code changes in order with the rest of the app.

even with the name, i can't find info on this, so i guess i didn't find it at the time, either...

Thanks for the link! I wasn't aware of this work, but it closely resembles my approach. I don't use cgi scripts, but I agree with Ward that ad-hoc, simple, browsing scripts are a great technique.

I call it Meta-dot :-)

Since I'm over my Norvig-recommending quota for the month, allow me some flattery. Just download any program from Darius Bacon's homepage. There are a lot of languages to choose from. I recommend Awklisp!

I am quite fond of Roger Hui's implementation of a J interpeter in C. The first couple of lines introduce macros that allowed Hui to code in a APL-ish style, instead of using the regular C idioms. A non-traditional example of language embedding.

I don't really remember why but I remember that reading agrep was a lot of fun. Keep in my, though, that I like the type of algorithms involved.

this (self link) has some recommendations.

OTOH Smalltalks environments typically provide a way to comment a class definition, which corresponds to 'purpose'. This is the start of one class comment: "Instances of class Fraction represent some rational number as a fraction. They can be created as a result of an arithmetic operation if one of the operands is a Fraction and the other is not a Float. All public arithmetic operations return reduced fractional results..."

Smalltalk environments are designed for searching & browsing (for classes & methods) rather than reading sequential program texts.

Many good suggestions there. Thanks!

I was kind of surprised by the J interpreter code. The lack of formatting was disturbing at first, but I can appreciate concise notation too.

Thank you all for your suggestions.

I'm not sure that many individual parts are especially breathtaking, but the Emacs design is worth studying. The Sawfish windowmanager became very popular with this design more recently. I'm still hoping the webbrowser folks will jump on board..

Emacs, like DrScheme, Java and the Express Project, is a programming language implementation extended to be a computing platform. This is a very powerful paradigm, and the best way I know to structure large programs.

It's too bad that every such project has to develop its own runtime. The JVM and .Net are OK, but IMO a serious programming language needs to have a native-compiled implementation.

And so the GNU Compiler for Java.

http://gcc.gnu.org/java/

To be clear, I'm interested in a better "computing environment", i.e. platform for writing programs that includes a coherent way of interacting with the user/programmer. Today we have a lot: Microsoft Windows, Unix shell, GTK/Gnome, KDE, Emacs, Wily, Squeak, to name a few.

"Better" is subjective of course. My favourite of the current crop is Emacs. Squeak Smalltalk seems much closer to my ideal, but I haven't been able to acquire a taste for it (I'm jealous of Squeak users). But I think it's okay to have different interfaces for different people (e.g. programmers vs. "grandmothers"), and only wasteful if a new interface can't attract enough users to sustain itself.

The subjectiveness is obvious since you say that the JVM and .NET are okay, whereas my brain switches off at the first mention of them. People working with those don't seem to share my sense of aesthetics, or are suppressing it because their intended users don't. Likewise people who are into GUIs based on GTK and so on - that's not the way I personally want to use my computer, it feels too low-level compared with Emacs.

The most promising development I see on the horizon is McCLIM. This is (as I understand it) a port of the Lisp Machine user interface to Common Lisp, so that you can run it on your PC. I view it as a step forward on the Emacs path by adding a presentation-based user interface and a more powerful (yet real-world proven) programming language, while otherwise being fairly similar in philosophy.

I would like to hear about other sophisticated computing environments that people are using today.

I agree. The Mozila platform (with Javascript, XUL etc.) is, perhaps, another example. Among the systems I chose to show my students this semester I chose emacs for exactly this reason.

Alas, not everyone shares our perspective. Joel Spolsky writes:

Suppose you take a Unix programmer and a Windows programmer and give them each the task of creating the same end-user application. The Unix programmer will create a command-line or text-driven core and occasionally, as an afterthought, build a GUI which drives that core. This way the main operations of the application will be available to other programmers who can invoke the program on the command line and read the results as text. The Windows programmer will tend to start with a GUI, and occasionally, as an afterthought, add a scripting language which can automate the operation of the GUI interface. This is appropriate for a culture in which 99.999% of the users are not programmers in any way, shape, or form, and have no interest in being one.

Er.. no. It's not appropriate, since it leads to programs that are less flexible and modifiable. That's an engineering problem, regardless of the OS you work on.

And, by the way, I don't think this has anything to do with Windows vs. Unix. It's about good design vs. bad design. You can produce good design on Windows, so I don't see why Joel feels he needs to make excuses for bad design, simply because some people think that these designs represent thw "Windows Culture".

Joel Spolsky next paragraph:

There is one significant group of Windows programmers who are primarily coding for other programmers: the Windows team itself, inside Microsoft. The way they tend to do things is to create an API, callable from the C language, which implements the functionality, and then create GUI applications which call that API. Anything you can do from the Windows user interface can also be accomplished using a programming interface callable from any reasonable programming language.

And grandmothers who program (need for large text?)

Powerful Personas