Code Renaissance is about building great teams and great software. By exploring best practices, team interactions, design, testing and related skills Code Renaissance strives to help you create the team and codebase that you've always wanted.

Quotes for Software Developers #1: Change

"It's better to put a stake in the ground and get started than it is to sit around waiting for perfect inspiration, the right timing and an unassailable position of strength. It's easier to navigate when you're moving. It's easier to criticize when you are standing still."
John Summers, HR Examiner

My take on it:

Everyday there are new opportunities for change. Is something on your team less than ideal? You be the one to try and fix it! Not being challenged at work? Do something on your own: learn something new, start a blog, create an App, or get involved in open source; challenge yourself.


Whatever your frustrations or your woes, stop whining and get moving. What are you going to do today to make things better?

Extending LINQ to Objects

To start off there seems to be a fair bit of confusion about what LINQ is because a lot of related technologies fall under that name. Here's a short list of Linq Technologies:

  • Linq Query Expressions - A declarative syntax similar to SQL. At compile time the standard query operators in the query expression get mapped to method calls.
  • Linq Providers a.k.a. Linq to [whatever] - whether it be SQL, XML, or custom providers these are data providers that work with Linq Query Expressions. 
  • Linq to SQL Mapping (Not to be confused with the Linq to SQL Provider) -  Microsoft created these specialized mapping tools for SQL Server though as you may have heard they will not be available going forward. Microsoft is dropping them in favor of the Entity Framework.
  • Linq Extension Methods - Each Linq Provider comes with a library of extension methods. Some of them match up to standard query operators and others have to be called using method syntax.

What I'll be covering is adding extension methods LINQ to Objects so that when you include the "System.Linq" namespace your new methods automatically get included. Any methods that are added should be in line with the other extension methods and should be carefully chosen; it would be very easy to clutter the namespace.

In the application I'm working on I need to check lists of objects for duplicates; if a duplicate is found then the list is rejected. Adding an efficient hasDuplicates method to the Linq namespace seems like a good option. Here's the code:

using System.Collections.Generic;

namespace System.Linq
{

 public static class DuplicateExtension{

  public static bool HasDuplicates(this IList list, Func areEqual)
  {
   for (int index1 = 0, lastIndex = list.Count() - 1; index1 < lastIndex; index1++)
   {
    for (int index2 = index1 + 1; index2 <= lastIndex; index2++)
    {
     if (areEqual(list[index1], list[index2]))
     {
      return true;
     }
    }
   }
   return false;
  }

  public static bool HasDuplicates(this IEnumerable list, Func areEqual)
  {
   for (int index1 = 0, lastIndex = list.Count() - 1; index1 < lastIndex; index1++)
   {
    for (int index2 = index1 + 1; index2 <= lastIndex; index2++)
    {
     if (areEqual(list.ElementAt(index1), list.ElementAt(index2)))
     {
      return true;
     }
    }
   }
   return false;
  }

 }

}

I created an extension method first for IList, which is what I needed, then copied it over and made some modifications for IEnumerable (since in general Linq to Objects methods support IEnumerable). Neither of these have been tested yet for efficiency and I suspect the IEnumerable one in particular can be improved upon.

Other than that everything is pretty straight forward. All I did is create extension methods in the Linq namespace. The first parameter (preceded by 'this') indicated the interface to be extended and the namespace was the namespace to be extended, in this case System.Linq. The static class name is not referenced when calling the extension method so it can be named anything you like. I guess the most surprising thing about digging into this was finding out there wasn't more to it.

The extension method above is very flexible and can be called as follows:

var dupicateFound = list.HasDuplicates((a,b)=> a.ToLower() == b.ToLower()

Given a list of items of type T then you pass in a method compare two objects of type T to determine if they are matched/duplicate. Here I'm passing in a lambda expression that takes two parameters of type T and returns a bool. In this simple example the signature is Func<string, string, bool> though you can work with lists of any object type and pass in a method that uses any sort of match logic you like.

Complicator's gloves

Anytime we're discussing over-engineered code around the office it's a safe bet that someone will mention complicator's gloves. Picture a pair of magical gloves that, when you wear them, bestow you with the ability to complicate anything you touch.

Photo by Arts

Complicator's gloves are synonymous with a mindset that is always looking for interesting and novel approaches and is the antithesis of K.I.S.S. methodology. I even use the term now in place of my all time favorite aphorism. The phrase comes from a TheDailyWTF story entitled The Complicator's Gloves that struck such true note with some of the developers where I work that it became part of the vernacular. While the usage in the story is slightly different, the concept is the same.

The Complicator's Gloves story is a story of people who revel in abstraction, indirection and patterns viewing them as fun little toys to build puzzles out of instead of what they are: key tools for reducing complexity. Often complicators justify their bad behavior by trumpeting how much lower the implementation overhead is for themselves (while remaining oblivious to the huge implementation and maintenance overhead they create for everyone else).

All programmers have a tendency to slip into the complicator's mindset from time to time and though most developers fight this tendency it's really easy to grab hold of a shiny new hammer and see every problem in the code as a nail. Mentally you look down and it's like "Complicators gloves? How did those get there?". When that happens, when you get that mental nudge that you are going astray, you need to mentally check yourself, take the complicator's gloves off and begin again.

Program like Hansel and Gretel: Leave a Trail

There's a lot to be learned from the story of Hansel and Gretel (like don't be evil or you'll get shoved into an oven) but the main thing that developers can take away from the story is the importance of leaving a good trail.

Here's the ultra-condensed version of the story:

  • Times are hard and there's not enough food for the family.
  • The children's father takes them in the woods and leaves them to die.
  • Fortunately Hansel left a trail of stones and they get home safely.
  • Again father takes them deeper into the woods and leaves them.
  • This time Hansel left a trail of bread and it gets eaten by birds.
  • Without a trail they're lost and get in a lot of trouble with a witch.

At this point you're wondering where I'm going with all of this, let me explain.

I'm living with a code base that uses a lot of very complicated code to do very simple things. It's not everywhere but there are several areas, mainly written by an overly intelligent former team member, that are pure hell to find your way through. You're stepping through the debugger and then... nothing. Something magic happened and the debugger didn't step you into it. There's no trail to follow; you're lost.

These nasty sections of code are the woods.

Something as simple as adding a few values to a drop-down means you have to trace back through six layers of javascript, including several callbacks and a proxy object, 5 layers of c#, a stored procedure and some nested SQL functions all to find out that a simple table change in the database was all that was needed. Wouldn't it have been nice if someone had left a comment saying "To change the values in this drop-down edit table x... oh and reset the app pool to get the changes to show up".

Lesson one is that if you're one of these hyper-intellectuals who enjoys building logic puzzles in code, don't. Instead design things so that there is an obvious trail through the code for us mere mortals to follow. I know, I know... simple is hard; let that be a challenge for you.

Lesson two is that as you find yourself hacking your way through the woods and get to know your way around, leave copious trail of comments for others to follow. Your team will thank you for it and who knows you may find your way through here again some day.

Lesson three is that not following lessons one and two is evil and evil people get shoved into ovens at opportune times... you've been warned!

Confession time: I worked my way through that nasty drop-down code on Friday and was so worn out when I finished at the end of the day that I didn't comment it. Come Monday I'm going to trudge back through there and leave detailed comments in the sections of code where the trail ends. Time to practice what I preach.

The Javascript void operator explained

I haven't seen a clear explanation of why we have the void operator in javascript so I decided to do a bit of research myself.

Picture (of Javascript Graffiti Art?) by S. Mason

The javascript void operator was introduced in the Javascript 1.1 specification. The explanation of void states:

  • The void operator takes an expression of any type as its operand, and returns undefined.

This is pretty straight forward though it's not entirely clear why that would be useful. One thing this clarifies is that void is an operator (not a function). Because of this void(0) is technically incorrect though in practice implementations allow it to be used this way it should be used without parentheses e.g. void 0. Also because it is an operator you can't assign it to a variable. This means that "var a = void" will throw an error.

Another thing that's important is that when it the specification mentions undefined it is not talking about the undefined keyword which is a global variable that wasn't introduced until javascript 1.3; instead it's talking about the undefined type which is a primitive type like string and number in javascript.

I also found another mention of void in the document:

  •  When a JavaScript expression is evaluated (executed), the result denotes one of
    three things:
    • a variable (in C, this would be called an lvalue)
    • a value
    • undefined (the expression is said to be void)

From this you can tell that undefined is strongly related to concept of void in C. In some early coding examples elsewhere I found code that said "if(a === void 0)", so it looks like early on (in practice if not by intention) void was a common way to get the undefined value for comparison. For instance the following will display true: javascript:alert(undefined === void 0).

This can still be useful. As of the currently implemented specification the undefined property doesn't have to equal undefined, so javascript:undefined=4;alert(undefined === void 0) returns false (though in IE9 and Firefox 4, per the ECMA 5 spec, undefined is no longer writable, so this returns true). Because of this, if you are writing code that will be executed in someone else's web page (an ad perhaps) you may want to use void 0 in place of undefined. As more browsers support the ECMA script 5 specification this will be less of an issue.

Some sources I've read suggest the sole reason that void was put in specifically for anchor tags (a hack that is so often debated), but I have found no evidence of that.

I hope this information helps though, outside of anchor tags, I'm still unclear on it's real usefulness. If you have any coding examples that show where void is helpful please share.

Brown field software: The five rules of code maintenance

As previously described (picture a cow pasture) brown-field development is the maintenance of an established project after the initial developers, working under tight time constraints, have pooed all over the place.

Photo by Fabio Rava

With that in mind here are 5 simple rules to help you clean up your code base:

  • #1 - Always leave the code cleaner than you found it.

    This is both common courtesy and common sense. Think of the most brittle and painful code you've ever worked with. It didn't get that way all at once. Person by person, edit by edit, deadline by deadline it slowly descended into a blackhole of entropy.

    A vicious cycle ensued: the more brittle that code became, the longer each change took and the more the developers complained there was no time clean it up. Do yourself a favor and clean as you go... you and your team will be the better for it.


  • #2 - Never clean up code that will not be tested.

    Cleaning up code that's not going to be tested is like playing Russian Roulette; if you clean up enough code eventually your luck will run out. That's why it's critical to only change code you know will be tested.

    If you're fixing a bug or adding a feature that code should already be covered by either unit tests or human testers (QA/QC), so you're golden. If you see other code that's in desperate need of a clean up but isn't covered by tests then either arrange for tests or leave it alone.

    Whats the worst that could happen? A really nasty subtle bug slips into production and isn't immediately caught. Depending on the application this may be a minor inconvenience or the end of the world. Manage your risks accordingly.


  • #3 - If you mix your refactoring with your maintenance its not refactoring.

    Refactoring by definition is changing structure without changing functionality. Making structural changes while making functional ones is a sure way to find yourself at a dead-end that requires you to roll back everything you've done (or worse yet end up with a brittle working mess that's near impossible to straighten out).

    Refactor. Test. Check-in. Repeat as necessary. Then make functional changes.

    Its best to refactor first for clarity. This makes the code easier to understand and gives you a solid place to roll back to. Once that's checked in refactor again to make it the specific pieces that need to be changed easier to work with. Often this means isolating the code the code that you will change in its own functions and even adding pseudo code to note the expected changes. Check in again.

    Make functionality changes, test and check in again. After your changes are complete you can refactor again if needed to clean up your own mess.


  • #4 - Incremental improvements are more stable than large sweeping ones, don’t try to fix everything all at once.

    Small changes are easy to understand, easy to validate and easy to undo if they cause problems. In systems of any complexity large changes are difficult to understand and are likely to have unintended side effects which will be difficult to identify and resolve. 


  • #5 - If you have taken the time to understand difficult piece of code then take a little more time to make it more clear.

    This may be renaming variables, functions or classes to match their purpose or more complicated refactorings or it may be as simple as adding comments to the code.


Following these tips consistently over time (especially if done as a team) can make your brown field a cleaner and a more pleasant place to be.

If you have any tips you'd like to share please leave a comment.

Green field software: five rules for writing maintainable code

If you're not familiar with the term green-field development the analogy works like this: the field is the project, developers are cows and poo is other people's hard to maintain code. Brown-field development is code maintenance and is so named because other developers have already pooed all over the place.

If you're lucky a few times in your career you'll get to take on a new project from scratch. That's green field development.On a smaller scale it could be a new control, web page or application feature that doesn't really depend on the existing code base.

Keeping this in mind here are five simple rules to make your code easier to live with over the long term and make the field a little less brown for those who come after you:

  1. 1) Don't write something in one line of code if two lines is more easily understood.

    Having multiple operations on a single line is a code smell; it makes code more difficult to understand and harder to debug. Given a choice between conciseness and clarity, choose clarity.


  2. 2) Name things well; rename them early and often.

    How well things are named plays a huge role in the maintainability of the code. If you find that the name of a variable, property, function or class doesn't match its purpose then rename it; the earlier you do this the easier it will be. If you find a function or class is difficult to name that's often a sign that it's not cohesive and/or needs to be refactored.


  3. 3) Avoid premature optimization.

    Optimized code tends to be less readable. Given a choice between clarity and performance, choose clarity unless speed has proven to be a problem. If speed becomes a problem identify your bottleneck, fix it and comment the optimization explaining both how and why.


  4. 4) Follow the style of the existing code where possible.

    Consistency makes code easier to understand. Teams should try to converge on a single style. As a team member let go of your preferences and emulate the status quo where possible. If the status quo sucks then work with your team fix it.


  5. 5) Keep the code as simple as possible but no simpler.

    When solving a problem in code look go for the simple solution first. Simple solutions are easily maintained and easily changed. Having explored a simple solution and understood the problem it's easier to refactor to something to more complex if necessary. In contrast novel solutions tend to be hard for others to understand and maintain... pursue those on your own time, for fun.


What about you? Are there any tips you have for writing maintainable code?