Hugoware

The product of a web developer with a little too much caffeine

Programming – AKA: Paint By Number

with 7 comments

This last week has been pretty busy for me. I’ve been working on several projects at work, deadlines coming due, trying to get personal projects done, jLinq bugs fixed — it’s been a rough week.

I was excited a few weeks ago when the new developer was going to start. I was finally going to be able to spread out some of this work and get a little more time on my hands… or so I thought. As it turns out, this guy isn’t exactly what I was expecting. Despite my best efforts, I still ended up hiring someone with pretty much no background in programming. I went from already being maxed out to now spending between 20% to 30% of my time teaching the basics of programming… yeah – this is my fault.

But as bad as it sounds it really has actually helped me rediscover a programming rule that I thought I was still using but apparently had forgotten.

So, one of the first projects the guy had to do involved checking a directory for new files, creating a record of the file if it was found and then processing existing files to transform file types from one to another. Really, probably an hour long job at most but was really causing this guy some grief.

An Alternate Approach — Simplicity

Naturally, as a developer, the first thing I started trying to explain was how the code would work like checking file dates or creating an XmlSerializer to load and save files — none of which actually helped him solve his problem. After several frustrating whiteboarding sessions I came up with a new route — make it so simple it was impossible to mess it up!

I took a second pass at trying to get the guy started in the right direction. Instead, I opened a new class file for him and wrote something like this.

public class FileRecordSync {
    //snip...

    //This is a list of the files that the program has already detected
    //this is also where to add new files that are discovered
    public List<FileRecordEntry> CurrentFiles { get; private set; }

    //determine if this file should be processed or not
    public bool IsValidFileType(string path) {
        throw new NotImplementedException();
    }

    //check and see if this file exists in CurrentFiles or not
    public bool IsExistingFileEntry(string path) {
        throw new NotImplementedException();
    }

    //check to see if the modified date is greater than the logged modified date
    public bool IsFileEntryModified(FileRecordEntry entry) {
        throw new NotImplementedException();
    }

    //find the matching file in the CurrentFiles or return null if nothing was found
    public FileRecordEntry FindExistingEntry(string path) {
        throw new NotImplementedException();
    }

    //create a new FileRecordEntry from the path and add it to CurrentFiles
    public void AddNewFileRecordEntry(string path) {
        throw new NotImplementedException();
    }

    //set the file as expired to 
    public void MarkFileAsModified(FileRecordEntry entry) {
        throw new NotImplementedException();
    }

    //snip...
}

Granted, an experienced developer could place all of those functions into a single loop and it would still be readable but isn’t the code above the kind of code we should all be writing anyways? Simple, clear, straight-forward functions each with a specific purpose and nothing more?

Code like this manages complexity – he didn’t have to worry about how each of the functions were going to fit into the master plan but instead how to complete each of the functions.

You know what coding like this makes me think of – Paint by number! And when it comes to code complexity – that’s a VERY good thing.

paint-by-number

It’s hard to tell what that is a picture of looking at it now — but if you remain diligent and fill in each of the blanks with the correct color then before long you’re staring at a masterpiece (or maybe not — this picture looks like someone holding a gun in FPS view — but you get the idea :))!

When it was all said and done with, the loop that had caused so much grief was much easier to read – not just for him but easier for me to read as well!


public void ProcessFiles() {

    foreach(string file in Directory.GetFiles(folder)) {

        if (!this.IsValidFileType(file)) { continue; }

        if (this.IsExistingFileEntry(file) &&
            this.IsFileModified(file)) {
            FileEntryRecord entry= this.FindExistingFile(file);
            this.MarkFileAsModified(entry);

        }
        else {
            this.AddNewFileRecordEntry(file);

        }
    }

}

Even without comments, you can most likely figure out what this code does with only a cursory glance over it.

A Personal Reevaluation

Its hard to say when a developer abandons simplicity. I think a lot of us start out writing gigantic functions that do much more than they need to and then slowly realize how much easier our lives are if we create functions for specific jobs.

Ironically though, I think the smarter and more skilled we become, we begin to lose sight of what a “simple” function really is. Some of us can write a single lambda expression to create a ham-n-cheese sandwich with our eyes closed — a 20 to 30 line for loop can’t possibly be that difficult for us anymore!

I can’t deny that I would have pushed all that code into a single loop, used a handful of well named variables with a couple clear and useful comments and called it a day. But looking back on the final result I can say without a doubt that I’d rather go back and make changes to the new, simpler class — wouldn’t you say the same?

Advertisements

Written by hugoware

September 17, 2009 at 10:17 pm

7 Responses

Subscribe to comments with RSS.

  1. For me, one of the hardest things to do is to train some one and explain specs at the same time. Sometimes my ego gets in the way and I end up misconstrueing explaining what I want – “the system should do X, Y, Z” – with “a best practice is”. The instruction gets in the way of letting someone try to learn on their own. Too many times I have complicated things for someone else when I insist on “extensiblity” over GTD.

    My one good rule of thumb that I enforce with my team that has really paid off is the following phrase: “Can I read your code at 2 am and some understanding of what you are doing before I wake you up?” Two corollaries of these are: “What does var v10 mean?”; and “Write your code as though you are publishing it in an article.” This makes you take naming conventions seriously, as well consider what type of complexity you want to drop into someone else’s lap.

    I LOVE design patterns, but I have found that they can be a drag when someone else has debug them. It makes me think that my design is too complex, too.

    ActiveEngine Sensei

    September 19, 2009 at 11:33 am

    • Interesting to bring up design patterns – I didn’t even bother go into those with him when we got started. Mostly, we simply whiteboarded solutions and then split up the work.

      I’ve tried to keep my rules to a minimum. I haven’t worked on a team before but I imagine that someone placing rules and constraints of every aspect of development would become annoying. For the most part I want to let this guy learn so I kept the rules fairly compact.

      I gave him several of the normal rules (i.e. good variable and method names), but the big rule that I really emphasised was…

      Don’t make a change unless you understand why your change will fix the problem…

      I know it gets tempting to make a quick change and see if it fixes the problem – but I’ve always maintained that unless you know the why behind how your change actually fixed the program, then your program isn’t actually fixed.

      I think I said at one point ‘Making the compiler shut up isn’t actually fixing errors’

      Anyways, I’m new to managing “programmers” so any advice is welcome.

      webdev_hb

      September 20, 2009 at 11:14 pm

      • I’ve worked with a range of skill sets with people and currently I manage a team of 6, each having a variety of backgrounds. My first hire was a guy from accounting who had VERY strong business skills and a burning desire to learn, no matter the task nor the pain it took him to acquire new skills. While he had skill at MS Access and some SQL and some classes in programming he is a total newbie. I have to say that I’ve seen him progress the most out of all the team.

        Many times I have put him through trial by fire with it in mind that I may have to help him out, but it’s been worth it as he learns well from making mistakes. Right he has progressed to ASP.Net some rudimentary screen development.

        I’ve picked projects for him where I want him to reach certain level by the end of the year. This may mean starting something then having him complete it. We always sit down to complete spec’s together as I stress the importance of have a good model first before starting the solution.

        I’ve been lucky in that when I interview people I ask them to solve the problems that I’m currently struggling with or a thorny problem that I’ve solved in the past. This gives me insight into how they think and I can gauge whether I can ask them to step outside the box to implement a good solution. Then I ask the candidate to model the solution for me on a white board. It shows me how they think and if they break out of interview mode and do some thinking.

        In the end you have figure out where you can trust your direct reports’ skill levels. If you are training someone it may slow things down for you, but you get a great chance at instilling the values and the mentality that you feel are productive. I always ask – “Of the tasks I’m assigning, what value or lesson will this person gain from completing it besides getting something done.” It helps me decide what to assign and when. Hope this helps.

        ActiveEngine Sensei

        September 21, 2009 at 6:15 pm

  2. […] Pick of the week: Programming – AKA: Paint By Number […]

  3. hi, it also may be useful 15puzzles jQuery way

    jQuery drag-n-drop

    December 2, 2009 at 5:33 pm

  4. […] a long time now I’ve been pretty much a solo programmer — I only got an assistant in the last few months. But lately I’ve really been trying to reach outside that bubble and connect with more […]

    Speaking Of Code « Hugoware

    December 16, 2009 at 1:15 am

  5. […] Whenever I’m talking code with other beginning developers, this is the first point I start with. Complexity and clarity is one of the most difficult battles for a developer since the definition of ‘complex’ and ‘clear’ constantly changes. […]


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: