My best code review

In 1998 (or maybe 1999?) I was a fairly junior developer, but fortunate to be working under a really smart mentor (Aamod Sane).

Among many things that I'm grateful for was his relatively constant practice of helping me through constructive code reviews.

The one that sticks out, the one that changed my view of how to write my own code, started out with me excited with finishing the code and a few tests for some now forgotten task.

After reading through it myself to hopefully avoid really stupid mistakes ;) I kind of ran down the hall to get the attention of my supervisor/mentor.

Once he finished what he was doing we started walking back towards my workstation.

[...this is where it starts to get interesting...]


On the walk back towards my machine I was nervously and rapidly telling him what, why, and how the code does what it's supposed to.

[Me doing all this quick overview talking was important actually...]


We sit down at my machine, swivel the monitor over, and he start reading.

He....
sighs.



Then....
shakes his head.



Really. That's what happened.
Yes, you know what I felt like. ;)


If it had just ended there it would have been like any other awful code review (see http://www.osnews.com/story/19266/WTFs_m)



So, finally, the really good conclusion.

Before he left he said this to me:

Just make the code look like what you just told me.

That walk between machines earlier when I rambled my way through telling him what the code did was actually a fairly clear description of things. The code I had actually written was really detailed, messy, and all together just "code".


After the advice of my mentor, I looked at the code with fresh eyes and I could see better method names, better looping patterns, and just better ways to "tell the story" of what I was trying to do.


Now, I try to write my code so that it "reads" like a good story. Sometimes I do a really good job, and other times not so much, but I have a clear goal that I'm shooting for.

My Favorite Inverview Question

In a recent discussion interview questions came up, here's my favorite one.

To set some context this question is designed to gauge the abstract and critical thinking of a generally inexperienced developer. I don't usually use this for very experienced developers, but may if I think I'm getting shallow or suspicious answers.

Here's what I start with:

I'm friendly but not at all helpful while I do this.

• I draw it out by hand on a whiteboard or on paper
• I verbalize the relationships
• I offer to explain the notation and meaning of "is-a"
• I ask them to think out-loud
• I hand them the writing instrument
  

Then I just ask the candidate for their impressions of the model.

• What's good? What's bad? What would you change?

A few obvious things that the candidate should work their way around to:

1. A "Deer" is an animal also.
2. A "Cow" could be "Food" for a "Tiger".

After watching them squirm for a while, I then make one addition to the original model. I add a single method/operation to the "Animal" class.
Again, I ask them for their impressions.

If they don't get to it themselves I make sure to ask the following questions:

1. What happens if a "Deer" is passed to the eat method of a "Cow"?
2. How would you change the model to handle or avoid that problem?

Enjoy!

Comments, REST, Interactions, and Extensible Hypermedia

This post is to mostly keep track of the numerous blog threads going on about IDLs and schemas for REST. I find myself with more to say that wit to organize it... :(

First my summaries of opinions, then links to my comments here and there.

Some of my opinions on a RESTful Client Engine, and what types of server-side changes would NOT break a client:

• URIs are discovered (except the first)
• Server-provided data extensions (hidden fields with defaults in a form) are treated like "does not understand" but still submitted properly
• Changes to which HTTP verb are used. The server can swap PUT for POST without issue (verb is discovered in form not spec'ed in a schema)
• Changes in state path. "checkout" could directly be a single form with POST, a GET link to a single for with POST, a POST to a form with reliable PUT semantics, .......
  

Links,opinions on the changing landscape of content (and predictions of the future of hypermedia content):

• Sam Ruby's suggestions for HTML5 Distributed Extensibility is a fabulous starting point.
• URI Templates, HTML Forms, XForms, Web Forms, WADL
  
• XSD is being extended to better support versioning
• Data schemas designed for extensibility should allow everything possible to be optional
  
• Microformats enable opportunistic clients to machine process
• GRDDL leaps from microformats, xml, some json up to RDF
• HTML+Microformats can do a ton of this already, but with no machine processable anything
• Prediction: in 10 years all of this this will have exploded/merged into one or a few really cool and evolvable data/interaction schema systems
  

References to programming and type systems that address these issues more appropriately than any IDL (as far as I can get into them so far... :)

• from Stu Charlton comes a reference to interaction machines
• from Todd Hoff comes a reference to two NASA reference on Mision Planning and Closed Loop Execution and Recovery
• papers from Luis Caires, for example Spatial-Behavioral Types, Distributed Services, and Resources
  (forget where I found this material from... can't understand it yet...)
  

The following is a guide to my recent comments on these threads from around the web:

Subbu says:

Should this idea be extended to the rest of non-user facing resource-oriented applications? I don't think so. Here is why.

The idea of hypermedia embedding all the action controls necessary to interact with the server works well for an arbitrary number of universal clients interacting with a given server. In this case, the server offering a set of resources specifies all the ordering/interaction rules within the representation. Most application clients, on the other hand, interact with more than one server, and the ordering constraints can not be set by any given server. The clients know how to compose applications out of resources offered by various servers, and each client needs to be able to exercise control over composition. To be able to exercise such a control, client applications can not be universal, and the benefits that John lists above cannot be completely realized.

My comments is that clients should be opportunistic: if they understand some shared semantic (like a RESTful shopping API or task manager) then they can automate some interactions.

On JJ Dubray's blog I make several comments.

In response to "REST creates strong coupling", I say:

• JJ is ignoring the shared definitions of MIME types
• The globally shared "Provider external" (Pe) semantics in REST are (URI, GET representation, hyperlinks)
• in WS-* the Pe globally is 0 (zero), only particular shared uses have a shared semantic.
  

In response to "REST and inter-actions", I say (and say and say):

• For me REST in the enterprise isn't about scalability, but rather independent evolution and support for partial failure.
• In maybe 10 years there will be an XML schema language that properly supports versioning and extensibility

In Steve Vinoski's blog on "IDLs vs Human Documentation" I comment that:

• I side with Patrick Mueller: there is something of value in more than just prose to document RESTful systems
• Hypermedia MIME types are _more_ than just a data schema (embedded forms to signify actions)
• A list of RESTful interactions that _shouldn't_ break a programmed client (listed below)