09 November 2005

Programming language feature request: Point comments

Programming languages still don't have all the features I want. Here's an example.

I want point comments, special comments that briefly explain the point of the following block of code. The language would guarantee that whenever an exception falls out of a point-commented block of code, the point comment is automatically added to the resulting error message.

Here's some pseudocode that shows what I'm talking about. The characters //- denote a point comment.

 //- set up the flogmogger to do ${job}
 if baz

 //- forward the request to the remote agent on ${flogmog.host}
 env = new Rpc.Envelope
 reply = flogmog.send(env)

Here's how this would work. At the point where the comment appears, the system evaluates any variables that appear in the comment (in this case, ${job} in the first comment and ${flogmog.host} in the second). It stores the values on the stack and proceeds. If the chunk of code under that comment fails with an exception, the exception is automatically caught; annotated with the comment, including the pre-calculated value of any variables that appear in it; and rethrown. These annotations could be stored in a field of the exception object.

Then, whenever an exception object is called upon to create a user-visible error message, it includes these annotations to tell what the code was trying to do at the time of the error. Here's a sample error message:

    Failed to forward the request to the remote agent on localhost:
    RpcException: URI not found (/inventory/donuts).

Of course, if the caller had its own point comments, and the RPC module had its own point comments, you would get something more like this:

    Failed to order more donuts from Xylonium Nuclear Bakery:
    Failed to forward the request to the remote agent on localhost:
    Failed to confirm RPC transaction was successful:
    RpcException: URI not found (/inventory/donuts).

It's like a traceback--but instead of source code files and line numbers, you get meaningful English messages. I think both are valuable for programmers, and improved error messages are always welcome from the user's perspective.

A mechanism for achieving this level of error-message coolness exists in some languages: exception chaining. But really using it requires a lot of boilerplate try/catch/throw.

Another flavor of point comment should be provided to allow for internationalization. I had something like this in mind:

 //= flogMogSetup(job)

 //= forwardRequestTo(flogmog.host)

The actual error messages for each language would appear in separate message files, of course. Here flogmogSetup and forwardRequestTo are just keys into the localized message files.

Comments that actually do stuff are something rather, er, different; but pragmatism beats purity. If necessary, the syntax could be changed to look less like a comment and more like code.

A more significant critique is that these error messages still wouldn't be very good. I consider point comments another weapon against bad error messages. Maybe the ultimate answer is for programmers to spend thousands of hours really polishing the error messages their systems generate. I just don't think that's realistically going to happen. I think point comments would improve the baseline case. It's worth a shot.

No comments: