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.

Applying Test-Driven Development to Assessment in Software Engineering Education

Abstract: Test-Driven Development has become a predominant part of many Agile processes and an emphasis on testing has become a hallmark of modern software engineering discipline. Perhaps unsurprisingly, since Fred Brooks himself noted that software is made of "pure thought stuff", this innovation in software process has much wider applicability than merely the development of software components. In fact, one can argue that this very same approach should be taken to the task of teaching software engineering. In this paper, we review the educational literature on assessment in engineering education and argue that many of the principles behind TDD/BDD/ATDD should be applied by faculty for the administration and management of a software engineering course. We show how concepts such as "fail fast", "unit testing," and "iterations" can be used to manage course progress, and end with a framework that faculty can try in their own courses.

“Assessment as a long-term strategy is intended to enable high-performance student learning systems through the continuous measurement of processes and outcomes, and through the use of results to further refine performance.” (Spurlin, Rajala, Plavelle Designing Better Engineering Education Through Assessment 171)

Web Design for Developers

I started reading Web Design for Developers from the Pragmatic Bookshelf on Friday. After a couple of chapters, it seems like what I've come to expect from the Pragmatic Bookshelf (after The Pragmatic Programming and Pragmatic Thinking and Learning): clearly written, insightful, and worth a ponder. Here are my notes:

Chapter 2: The Basics of Site (Re)Design

"It's also important to realize that in the world of design, one person's masterpiece is another person's terrible design."

"Try to understand what your clients think they want from the site you are designing."

"Make sure you understand the real purpose of the site and that you have a feel for the intended audience."

"Once you have the requirements together, start sketching as you discover more. Sketch with paper and pen/pencil"

"Many developers say that clients don't know what they want. I'd say that they just don't know how to tell you."

"You should almost never come to the table with only one design."

"Some requests might not seem all that clear or reasonable. Don't feel overwhelmed when clients say they want the site to look more fun. Having heard this one myself many times, I can only say that you'll accomplish this one by brute force, trial and error, and a little luck. If you accomplish the rest of these requirements, then you'll be in good shape."

"Even worse is when the client asks you to create something exactly like an established site, except different...It might seem like a bad idea at first, but a comment like this is one that you should quietly ignore. Follow good design principles and solicit constant feedback from your clients, and these kinds of requests should work themselves out."

"If you break the requirements into logical steps, they might look like this:

1. Sketch some basic designs and get one approved
2. Select colors
3. Select fonts
4. Implement the basic design in Photoshop
5. Create images for the banner, buttons, and other elements
6. Create an HTML and CSS template
7. Test your designs for compatibility and accessibility"

"To sketch a design, you need to know what the site's layout should contain. What links should be present from the home page? What elements should the home page contain?"

"You've probably noticed that websites tend to have many things in common. Most have a header region that displays the site's name or logo. Many sites also have their main content region divided into columns, and at least one of those columns is often used as a sidebar region that might contain navigation elements or additional information. It's also likely that the site has a navigation bar either across the top of the page of along the left side. Finally, you can usually find a footer region that contains copyright information and maybe some additional links."

"Come up with at least three designs for your clients on every project. Provide a simple, conservative design; a complex design; and a design that aims for the middle, something mostly conservative that also has some splashes of flair."

"When your clients come to you asking for a new site design, get them to do some of the legwork for you. Ask them to identify a few websites they like. Get them to tell you what they like about them."

"I once heard a great presentation from Robert Martin about how writing software was like writing a book. You'll do a first draft and then a few revisions, refactoring until you get it just right, and that's your final draft. Design is kind of like that, except that after you go through all those stages, your client will see it and tell you that he hates it."

Chapter 3: Choosing Colors

"Colors can make or break your application depending on how you use them and blend them together. They evoke emotions and draw attention to important details. This is one of the most important chapters in this book because it helps you build the foundation of a great-looking site."

"You have a lot of things to think about when working with colors. You have to think about the shade of the color, the amount of color, and how the color looks along side other colors. You also need to think about how the color might be interpreted by your audience."

"When people talk about an object's color, they are referring to the hue."

"Saturation is the amount of color in an image. A saturated color is vibrant, whereas a desaturated color looks dull and gray. If you reduce the saturation, you make colors look washed out. In some cases, this is a good thing because it takes the edge off some otherwise harsh or shocking colors."

"Altering the brightness of a color can make the overall appearance of the colors darker or lighter."




"There is a fundamental difference between the way color works on paper or in nature, where light is reflected, and the way color works on a screen, where it is projected. On your screen, the color mixing is additive; in print, it is subtractive."

"When you're working with paints, crayons, and markers, you deal with the primary colors of yellow, blue, and red. You start with all of the colors of light mixed together *white), and filter out what you don't want to get the color you are looking for."

"A banana doesn't actually have any color. It doesn't have any light energy to produce color. Instead, a banana appears to be yellow because it reflects all the light waves that cause us to see yellow, while absorbing all the other waves."

"Computer screens display colors using the additive color system. The primary colors you've grown up with are replaced by red, green, and blue. These colors are mixed together and projected, creating the light."

"The context of a color can greatly influence how it appears in your application. Even if you technically pick the correct colors, you might have to make additional adjustments to make them look right."


"When choosing colors for your application, it's important to think about the various responses your choices might trigger. Using red or blue improperly could trigger an undesired response or could even create confusion."

"Your choice of color influences your users' perspectives, and simply applying a different color scheme to a website complete changes the user experience."

Warm Colors
"As the name suggests, warm colors make you think of warmth, sunlight, and heat. Some people believe you feel warmer if you look at these colors."

"Red is a strong color that can stand for love, joy, happiness, and romance. It can also represent lust, anger, war, an emergency, or danger. Its use in applications is almost always to show a warning or an error message. Red attracts a user's eyes immediately."

"It's hard for a user to focus on yellow, but the color can evoke feelings of intelligence and happiness when used correctly. Many applications use some sort of yellow fade effect to let you know the action you just took was successful."

"Orange can be cheerful like yellow, but it can also be arrogant and superior, depending on the amount of red."

Cool Colors
"Cool colors have a cooling or calming effect on people. They're comforting, and you can use them to tone down a site."

"Blue can be calming, soothing, and cool. It has a tendency to make users relax when it's desaturated. However, as the shades of blue get darker, they can cause feelings of sadness or depression."

"People tend to associate green with nature, hope, health, and responsiveness. However, if used incorrectly, green can also trigger feelings of envy...in addition to envy, green can evoke feelings of greed, guilt, and disorder. Certain shades of green allow the eyes to rest, which can have a soothing effect on your users. The wrong mixture of choices can make your users feel sick or disgusted."

"Purple is one of those odd colors that doesn't appear in nature very often. You might see it in the petals of flowers, but you see it mostly in things that people create. Purple is often associated with royalty and mysticism, mainly because it was extremely difficult to produce in ancient times. Purple is a mixture of red and blue, which means you get some of the attributes of each color. Light purple is often associated with nature, peace, tranquility, and spirituality. Dark purple can evoke feelings of depression. Large amounts of purple can be difficult on the eyes."

Neutral Colors
"Black, white, silver, gray, beige, and brown are unifying colors. They help bridge the gap between cool and warm colors. When used as background colors, they help other colors stand out."

"Black can represent prestige and elegance, and it can be pretty powerful if used in the right context. However, black is also associated with mourning, death, despair, and brooding. When you use black in a design, you must target your audience carefully."

"White evokes feelings of purity and perfection. It's a perfect color for a clean website. Too much white can be boring and sterile, but it makes every other color stand out that much more."

"Brown can stimulate hunger, health, and simplicity. On the other hand, some people observe brown to be a dirty color, and it can evoke feelings of uncleanliness, which is definitely not something you want for your site."

"Beige makes people relax. It is a conservative color that borrows from brown and white. It's a great choice for a background because it can be calming, and will allow other colors to stand out well."

"This color seldom evokes an emotion, but when it does, it's usually associated with feelings of gloom, mourning,