Big Bugs, small bugs

It's...(>_>)...(-_-)...not the small bugs and mistakes that we should be so nervous about finding. It's the big ones.

Consequently, when a problem is found the response should not be "PANIC/BLAME, THERE'S A PROBLEM" but "Hmph. Problem. How long will it take to fix? What does the fix entail? What was the cause of the issue? How can we learn to minimize the recurrence of this problem in the future? How can we at least minimize the impact of its issue?"


...at least for the small problems. When a big problem occurs that's a compound sum of small problems where nobody bothered to ask those questions, I think it's perfectly logical to hold people accountable. Massive failure deserves its recompense.

I work in software teams where the managers become very uncomfortable with the idea of "bugs" being found in their code. I am too. I want my code to be "bug-free." Clean, beautiful, elegant. A work of art on par with the Mona Lisa and the perfect features of Angelina Jolie/Jessica Alba in her time...

But that's really hard, with software. It solves big, complex problems. The bigger and more complex problem you're dealing with, the harder it is to focus on doing the little things perfectly. There are many an abstract algebrician who may forget a sign or two as they're walking through a derivation, many a writer who may forget to use perfect punctuation as they're trying to espouse a greater point.

On one hand, I understand the frustration with this. As a student who's trying to learn calculus, you don't know enough about the material to tell the professor when he's wrong. You're just trying to keep up, and he should've done the little things right in the first place! As a reader of content, I judge a writer who writes things like "it was in there best interests to do that" or "In you're face!" If a writer is as intelligent as her or she thinks her or she is, he or she should've written the content of their piece correctly, in all it's glory, in the first place!

...and yes, that "it's" was intentional for humorous effect, in case your wondering. As was that "your". Gotcha. :P

On the other hand, the "it should've been done right!" argument can only go so far. Humans are not perfect. We will make mistakes, out of sloth, oversight, or just plain ignorance. The idea that we should always "dot our i's and cross our ts" is a good ideal, but difficult to do in practice.

Perhaps it's just harder for me. Some people might call me "sloppy." I argue there's a depth/breadth trade-off. The more varied or broad your concerns, the less time and energy you spend on the execution details of each of those concerns individually. Plus, the more things you try to do, the more opportunity there is for something to go wrong.

Some people may disagree, but this seems to mimic the realities of life.

Inheritance and Composition: There and back again

I recently got an application request to provide a web interface for a mobile app. The would serve as a demonstration for the mobile app's features. Both apps connect to a cloud datastore that provides a REST API for content.

I've gotten to the point that, whenever I start a new app, I try to think pretty heavily about what could change. I could've hacked and slashed through it, but I wanted to take a few moments to follow the basic Gang of Four design principles.

• Encapsulate what varies


• Program to an interface, not an implementation

As cloud based services are still new, and a relatively unstable market, my immediate thought was:what if we switch from one to another? Should the entire app need to be re-written? I say No.

Consequently, I wanted to encapsulate the variation of datastore. Ideally, my Domain model could remain as free as possible from specific provider concerns. It should focus on just the application function interactions.

I decided to build the app quickly in a framework that I'm comfortable with and enjoy, Grails. Grails boasts an advanced application architecture that really takes the concepts of Fowler's Patterns of Enterprise Application Architecture such as a Service Layer (something Rails does not seem to have out of the box, though it supports something kind of similar in "Helpers"), Data Mapper, Domain Model, Template View, Front Controller, and many other pieces that enable a competent, enterprise level senior developer to comfortably focus on building a god application from solid software engineering principles without having to build everything from scratch.

My initial approach was to handle this encapsulation of concepts in the Service Layer. The controller should only know about a Facade DatastoreServicewhich internally delegates to the application provider API.

Seeking to follow the concepts of Clean Boundaries from Uncle Bob Martin's Clean Code , I defined my own application level interface for the datastore. I then define a subinterface that extends that interface for the specific application provider, augmenting it with methods to encapsulate the REST API calls. An abstract class implements invariants of that interface and provides an extension point for the implementing service.

At this point,I'm starting to get worried. I seem to be adding a lot of complexity to the application for a very basic desire. Especially when further implementation of functionality made me need to store the 3rd party library's unique indentifier for my subsequent querying. As I tested, built, and refactored, I found my application as internally at odds about how to do this as I was.

On one hand I've used an inheritance hierarchy to store the 3rd party API's object id in my Domain Model. On the other, I have such a slim Facade over the 3rd party API in the service layer that it's just noise. I have two options:

1. Remove the Datastore service and have the DemoController directly talk to the ParseService.


2. Refactor the Domain Model to tease apart the 3rd party API id.

At first, I wasn't comfortable with the concept of option 2. It seemed conceptually strange. A Zapper IS A ParseEntity, and so is a ZapCard. Until I realized that what I'm saying, within the concept of my application, is that Zapper HAS A ParseIdentity. In effect, I'm saying that my Domain Model exists outside the context of the datastore,but has a representation within it.

This is conceptually interesting. We are used to thinking about the world in terms of how things are. I am a Person. I am also a Student. All Students are Persons, hence a Student IS A Person. But I'm not just a Student. I'm also an Entrepreneur, Engineer, Activist...How can I reconcile all of this without multiple inheritance?

Instead, what if I am a Person, who HAS A Student identity, HAS A Engineeridentity, etc etc. Then I can have a single canonical representation, and assume different roles in different contexts. When I have to activate pieces from a different context (such as drawing upon my Student.study() within an Engineer context, this process is simplified. Instead of having to cast myself into a different role, my fundamental representation is invariant (Person) and calls for identity are delegated to the appropriate concept. Or, to flip this in reverse, when I am a Student I need to access information that I have as a Person, I access it from my internal Person representation. Like a Russian Egg. Hence,prototypal inheritance built from composition.

How many tests would you write for this?

Working through Michael Feathers' Working Effectively With Legacy Code, I find myself wondering how many tests I should write for this.

Naively, I only have a public method. I only need to write tests to validate that method's externally facing API, right?

That feels wrong, though. The private method is doing "interesting things." It's connecting to a web API to update a local cache of data. If the data that's expected is not there after the update,it's telling the API to create that data. Although I've split up work by the methods to provide an easy API for the client view, because the public method internally has different conditions that it performs differently under, I should have tests that stress those different paths:

• When both user and card exist in local cache (already tested)


• When a user exists in local cache, but no card


• When a card exists in local cache, but no user


• When neither exists in local cache

Since I'm only testing the controller, I should mock the datastore service in each case. Simple enough, though it seems rather surprising that such a seemingly simple method should have so many execution paths. I suspect there is a refactoring hidden here that makes things a bit cleaner. But I can't find it right now.

As I work through such scenarios, I'm starting to see why Uncle Bob Martin says Objects Should Do One Thing in Clean Code. It's easier to test small objects that do one thing with simple tests: did it do it? Did something within an expected set of "untowards" happen?

I'm also starting to see how judicious use of objects starts eliminating branching statements (using an Abstract Factory instead of a giant switch/case for instantiating objects, for example.) As logic is pushed out to self-contained objects that encapsulate it, dynamically configurable behavior (via run-time Dependency Injection) allows for piecing out the number of things that happen in one place and putting them under test in another. The amount of unit tests for individual components becomes small, and all you need is a few integration/functional tests to verify everything knits together correctly at runtime.

It also makes me wonder about the necessity of visibility modifiers(public, private, protected). Essentially, at small enough levels of work, those things perhaps become unnecessary. If private methods should usually be refactored into distinct objects that encapsulate a small piece of work and expose a public API (e.g. DemoController's private populateFromRemoteData() should be the PopulationService's public populate() method, then it almost becomes unnecessary to have visibiity modification.

Of course, dynamic programming languages have worked under this assumption forever. What if LISP had it right all along? The key is, one has to change one's very style of writing code to truly see this benefits. If one writes giant globs of functions (10+ lines, doing many things) in LISP, you're in the same place as you are with OOP. In which case, you need to have the ability to hide certain things, ignore certain things, just for overall system comprehension.

After all,one of the original purposes of David Parnas' treaty on Information Hiding was that it made software easier to understand, in the design sense. Encapsulation enables reasoning about a system because it abstracts away irrelevant details. Modules are designed to contain cohesive pieces of functionality that expose an interface, in the original Parnas paper.

One can argue that visibility modifiers mean that the imperative style took the wrong approach from his observation. One can argue that classes act as "mini-modules" when they have private methods that are internal and public methods that expose an external interface. Instead, the private methods should be public methods of separate sub components within the module.

This doesn't take into account the "access control" piece of the puzzle, the idea that there's certain invariant information that you don't want clients replacing at runtime because it breaks your functionality. Yet the use of reflection and metaprogramming is only increasing because of the way they dramatically simplify programming. These tools typically blow right past access control. For example, Groovy secretly doesn't respect private. It's a convention that programmers don't use metaprogramming to modify privates.

Perhaps that really is a case of "you break it, you bought it?" But then what are the implications for software security models?

Programming War Stories

I recently read the following amusing snippet in Clean Code:

Client-Based Locking

This strategy is risky because all programmers who use the server must remember to lock it before using it and unlock it when done. Many (many!) years ago I worked on a system that employed client-based locking on a shared resource. The resource was used in hundreds of different places throughout the code. One poor programmer forgot to lock the resource in one of those places.

The system was a multi-terminal time-sharing system running accounting software
for Local 705 of the trucker’s union. The computer was in a raised-floor, environment controlled room 50 miles north of the Local 705 headquarters. At the headquarters they had dozens of data entry clerks typing union dues postings into the terminals. The terminals were connected to the computer using dedicated phone lines and 600bps half-duplex modems. (This was a very, very long time ago.)

About once per day, one of the terminals would “lock up.” There was no rhyme or reason to it. The lock up showed no preference for particular terminals or particular times. It was as though there were someone rolling dice choosing the time and terminal to lock up. Sometimes more than one terminal would lock up. Sometimes days would go by without any lock-ups.

At first the only solution was a reboot. But reboots were tough to coordinate. We had
to call the headquarters and get everyone to finish what they were doing on all the terminals. Then we could shut down and restart. If someone was doing something important that took an hour or two, the locked up terminal simply had to stay locked up.

After a few weeks of debugging we found that the cause was a ring-buffer counter that had gotten out of sync with its pointer. This buffer controlled output to the terminal. The pointer value indicated that the buffer was empty, but the counter said it was full. Because it was empty, there was nothing to display; but because it was also full, nothing could be added to the buffer to be displayed on the screen.

So we knew why the terminals were locking, but we didn’t know why the ring buffer
was getting out of sync. So we added a hack to work around the problem. It was possible to read the front panel switches on the computer. (This was a very, very, very long time ago.) We wrote a little trap function that detected when one of these switches was thrown and then looked for a ring buffer that was both empty and full. If one was found, it reset that buffer to empty. Voila! The locked-up terminal(s) started displaying again.

So now we didn’t have to reboot the system when a terminal locked up. The Local
would simply call us and tell us we had a lock-up, and then we just walked into the computer room and flicked a switch.

Of course sometimes they worked on the weekends, and we didn’t. So we added a
function to the scheduler that checked all the ring buffers once per minute and reset any that were both empty and full. This caused the displays to unclog before the Local could even get on the phone.

It was several more weeks of poring over page after page of monolithic assembly language code before we found the culprit. We had done the math and calculated that the frequency of the lock-ups was consistent with a single unprotected use of the ring buffer. So all we had to do was find that one faulty usage. Unfortunately, this was so very long ago that we didn’t have search tools or cross references or any other kind of automated help. We simply had to pore over listings.

I learned an important lesson that cold Chicago winter of 1971. Client-based locking
really blows.

These are great kinds of stories that really build programming culture. Like The Story of Mel and Real Programmers Don't Use Pascal. Or The Practice of Programming: A War Story. I know we have our Stack Overflows, Daily WTF, etc etc...but it seems like a site that stores such "programming war stories" would be valuable for the "cognitive apprenticeship model" of helping students/novices embracing the culture of their field.

Cleaning unclean jQuery

jQuery enthusiasts love chaining. They think it's the bee's knees, the cookie's crumbles, the frosting on the cupcake. In the name of "performance" for "not having to do multiple lookups", they tend to write code with anonymous functions everywhere, full of deep levels of nesting, with relatively nasty control structure. After reading Clean Code, I see a better way. Compare these snippets.

Engineering Education and Cognitive Load Theory

Engineering topics have higher intrinsic load than other fields because, as Wouters et al (2008) put it: "The more complex a skill, the higher the intrinsic cognitive load because of the higher element interactivity."

Loading files in Grails without application context

Like all Grails n00bs, I got into a pattern of loading a bunch of data into the DB in Bootstrap.groovy, a la

def init = { servletContext ->
        println "starting"
        if(!Role.list())
        {
            setupRoles()
        }
        println "roles set up"
        if(!Person.list())
        {
            setupPersons()
        }
        println "people set up"
        if(!Organization.list())
        {
            setupWorkgroups()
        }
        println "orgs set up"
        if(!Customer.list())
        {
            setupCustomers()
        }
        println "customers set up"
        if(!Project.list())
        {
            setupProjects()
        }
        println "projects set up"
        if(!Milestone.list())
        {
            setupMilestones()
        }
        println "milestones set up"
        if(!UserDefaultMilestone.list())
        {
            setupDefaultMilestones()
        }
        println "default milestones set up"
        if(!OrgGoals.list())
        {
            setupOrgGoals()
        }
        println "goals set up"
        if(!IMBO.list())
        {
            setupIMBOs()
        }
        println "imbos set up"
    }

Eventually something inside said that 800 line Bootstraps were a bad idea (reading Robert Martin's Clean Code is having an effect.) I decided to abstract that away with the Strategy Pattern:

I've recently discovered Fixtures, so I may move away from this approach, but I like the ability to encapsulate my creation steps in my classes and do more processing, so we'll see.

public interface CreationAlgorithm {
    void loadData();
}

import edu.asu.engineeringed.Media
import org.codehaus.groovy.grails.commons.ApplicationHolder

class MediaCreation implements CreationAlgorithm {
    public static void loadData(){
        createMedia()
    }
    
    private static final void createMedia() {
        def media = 
        [
            "awesome" : [ 
                          name:"Awesome",
                          description: "This picture should make you smile",
                          fileName:"images/awesome.png" 
                        ]
        ]
        
        media.each { k, v ->
            def grailsApplication = ApplicationHolder.application
            def resource = grailsApplication.mainContext.getResourceByPath(v.fileName)
            def theFile = resource.file
            def newMedia = new Media(fileData:theFile.readBytes(),
                                  name:v.name, 
                                  description:v.description)
            newMedia.save()
        }
    }
}

import ProfessorCreation
import PresentationCreation
import UserCreation
import BasicCreation
import CourseCreation
import ResearchCreation

class BootStrap {
    def init = { servletContext ->
        BasicCreation.loadData()
        ProfessorCreation.loadData()
        PresentationCreation.loadData()
        CourseCreation.loadData()
        UserCreation.loadData()
        ResearchCreation.loadData()
        MediaCreation.loadData()
        AccomplishmentCreation.loadData()
    }
    def destroy = {
    }
}

The MediaCreation bit was an interesting case. I read this post, but didn't like the approach of putting my files in the grails-app/conf directory or that I had to do it in Bootstrap.

I didn't wanna pass the Grails servletContext to that one as it would break the consistency (eventually I'll refactor it down to using the Groovy Spaceship operator on a map of interface instances or do some metaprogramming magic), so I had to figure out how to get the grailsApplication in a Groovy src/ class file. This showed me the way, and since Spring WebApplicationContext offers an interface for Resources it made the code nice and clean.