The Joel Test Revisited

The ubiquitous Joel Test: 12 Steps to Better Code is almost 20 years old. It was a great foundation, but with the past two decades, is it still relevant? Here’s my review.

1. Do you use source control?

Still valid and vital. But good source control practices are required. Have a master and a staging branch that can’t be pushed to directly. Do pull requests (i.e. peer reviews). Don’t push passwords, put that in a secure vault, scan for personal emails.

2. Can you make a build in one step?

This needs to be broadened to encompass all of CD/CI. Building, testing, and deployment should be one step in a dedicated setup. I’m currently using Codeship for that and loving it!

3. Do you make daily builds?

Again, CD/CI makes this better: build on every change. Less than this is too risky. And days without changes don’t need a build. Come on.

4. Do you have a bug database?

Yes! Essential. But it needs to be curated. If clients can add to it the bug descriptions might be too broad or too vague. Great clients will get that and learn to formulate bug reports correctly.

5. Do you fix bugs before writing new code?

My heart bleeds for this one. Reality will make you classify the bug from trivial to blocking, and bugs that can be worked around will be pushed aside to favour newer features. Fixing bugs first is good advice, but not always workable. But if our aim is the original “better code”, this is a sound practice.

6. Do you have an up-to-date schedule?

Still relevant, knowing that schedules will change on a daily basis. Agile has impacted this greatly. Devs see one sprint ahead, which might be a boon for when it comes to stress management.

7. Do you have a spec?

Specs are so volatile… Needs change fast. Write them down but keep updating them. And how about adding : do you have architectural documentation for when the project is done and slides towards long term maintenance?

8. Do programmers have quiet working conditions?

The first question that’s about the worker building the product. This one could be the toughest in some contexts. And silence isn’t the only factor. We work sitting down. The body takes a toll. Ergonomics are vital. And many programmers don’t like basements, contrarily to some rumours.

9. Do you have the best tools money can buy?

Be smart about this one. So many good tools are free now. And so many essential (and admittedly non-essential) tools are costly. Having to support software using an SDK without access to documentation shouldn’t be an assignment. Machines should be able to be up 100% of the time and perform adequately. Anything too old and slow should be replaced. Fast and stable Internet is vital too. This is what’s running the world now. Everyone should know.

10. Do you have testers?

Yes! Still valid! Programmers 👏 Aren’t 👏 Testers 👏!

11. Do new candidates write code during their interview?

Still valid. Interview questions shouldn’t be gotchas, ever. But problem solving is essential. Just don’t look for syntax errors. That’s not what handwritten coding is for.

12. Do you do hallway usability testing?

If the list was “12 steps to better products”, this would make sense. But this is for better code. A better question would be: Do you have unit tests? Doesn’t have to be TDD. Doesn’t have to be 100% coverage. But more than 0%.

Other questions for better code:

There are other questions that can lead to better code. Here are my additions:

13. Do you use design patterns?

There is such a thing as too much of a good thing though. A metric that could help: Ratio of singletons to other regular classes. Too many singletons means the developers just don’t know when to use them.

14. Do you upkeep the code?

When code is revisited, is it updated to meet new standards? Think ECMAScript 6 and what it brought. Were Promises revised (when appropriate) with the new async/await patterns?

15. Are programmers encouraged to explore new technologies?

This can be facilitated in a few ways. It doesn’t need to be paid time (but it can and boy does this make a company stand out!) If paying for this time as work hours isn’t possible, there are other ways. This is the sort of thing for which you bring out pizza, not at crunch time. Work isn’t a hackathon. If there’s crunch time, meals aren’t an incentive, they’re a facilitator, and extra time means extra pay. No exceptions, unless you want to compromise quality.

16. Is pair programming encouraged?

Some places consider this to be a net loss. Two programmers working on one feature together or two programmers working on one feature each? That’s easy to figure out! Well, no, not so much. If code quality matters, encourage occasional pair programming, and try to mix up the teams.

Fast distance calculation between geo-coordinates

I see this in libraries and it makes my skin crawl: the Great-Circle distance calculation (or GCDC). It is needlessly precise and slow. You will feel the performance hit if you have to do an O(n!) or even O(n log n) operation to sort or cluster points. And its precision is its downfall:

It takes into account the variation of the curvature of the Earth. It’s precise to within less than a meter.

This is too much work for what we need in most cases: a good approximation of distance between two points.

Here is a faster way that’s close enough:

//Supposing:

//lat1 and lon1 as coordinates of position 1;
//lat2 and lon2 as coordinates of position 2;

long meridional_circ = 40007860; // meters
double lat_degree_distance = meridional_circ / 360; // average length of one degree of latitude, or about 111133 meters.
long equatorial_circ = 40075017; // meters
double lon_degree_distance = equatorial_circ / 360; // average length of one degree of longitude AT THE EQUATOR, or about 111319 meters.

//calculate distances separately

double lat_distance = abs(lat1 – lat2) * lat_degree_distance;
double lon_distance = abs(lon1 – lon2) * lon_degree_distance * Math.cos(Math.PI * ((lat1 + lat2)/2) / 180);

//calculate Euclidean distance

double distance = Math.sqrt(lat_distance * lat_distance + lon_distance * lon_distance);

Declare the constants as constants, and you’re good to go. 

Optimization series: steps 0 and 1

I will be doing a series of posts on optimization, namely software optimization for speed, in the coming weeks and months. Optimization is by far my favourite thing in programming. To me, there’s nothing quite like taking code that works and making it code that works faster. I don’t get to do it as often as I’d like, and the same will probably go for you, whether you want to or not, but I will share what knowledge I’ve garnered over the years doing this.

 

Step 0: Pre-preparation

 

(Of course this is 0-indexed…) The very first step, and please pay attention, is that YOU MUST NOT, UNDER ANY CIRCUMSTANCE, BEGIN WITH THE OPTIMIZATION. That is: FIX THE BUGS FIRST. This is critical, optimization is very often a feature, or at the very least a defect correction, but more often than not an improvement. If you speed up code that doesn’t work, it will only crash faster. There is such a thing as preemptive optimization which can lead to more trouble than worth it down the road, and it’s a documented pitfall. Consider yourself warned.

(It goes without saying that standard programming practices must be applied, such as having backups and using a form of version control for your code. You must set that up if it’s not, for your own sanity as well as for the needs of the work ahead.)

 

Step 1: Preparation

 

With a stable codebase and no (known) bugs, we can begin. Optimization (and this is one of the reasons that makes it so attractive to me) is like experimental science. In science experiments, there is a very important notion that applies here. Scientists call it control. For example, for pharmaceuticals, there is usually a “control group” which is given a pill that does nothing, a placebo, along with other groups which will be given the actual drugs being tested. In the end, every subject took “a pill”, and that’s the scientist’s basis for analysis and comparison. This is also taught in high school science: don’t contaminate your samples, which is another way to say “don’t introduce unknowns.” It’s the same thing with software, but we’ll usually talk about benchmarking.

What you need to do is have all the conditions required in order to run your benchmark, in such a way that you can get back to it easily. That could mean working with backup databases, test files, virtual machines with snapshots, etc. If your optimization requires something more “exotic”, say simulating a faint wifi signal, near capacity memory or CPU usage, etc, you need to be able to bring up those same conditions, so that when you test your changes, you’re actually only testing your changes. In all cases, a reference base is needed, an initial state of input. So your first step (well, after fixing the bugs), is to BE ABLE TO EASILY GO BACK TO YOUR BENCHMARK FOR REFERENCE AND COMPARISON. This also implies being able to compare the end result, not just for speed but for accuracy. Because optimization is about finding a quicker route from point A to point B, not ending up at point C.

Got that? Don’t come back until you have that.

Rounding in .NET: A fair warning

Everybody uses the same rounding they learned in school. Only Siths deal in absolutes, as they say, but this is really really basic: .0, .1, .2, .3, .4 round down, and .5, .6, .7, .8, .9 round up. We’ve all learned this in school.

.NET Framework designers have taken it upon themselves to make fools of us all by defaulting the rounding algorithm (used by Math.Round) to something called “Banker’s rounding.” It behaves the same, except for .5, which will round to the nearest even integer. 2.5 rounds down to 2, 3.5 rounds up to 4. This was done so as to distribute .5 evenly up or down. Or a better explanation might be…

Counting objects

This is a variation on the classic C++ approach, adapted to C#. While .NET has its Garbage Collector which takes care of all objects you don’t need, at some point one might need to track how many instances of an object were created, or are active.

public class SomeClass
{
    public static int ObjectsCreatedCount = 0;
    public static int ObjectsActiveCount = 0;
    public SomeClass()
    {
        ObjectsCreatedCount++;
        ObjectsActiveCount++;
    }
    ~SomeClass()
    {
        ObjectsActiveCount--;
    }
}

That way, you can use SomeClass.ObjectsCreatedCount to know how many objects were created, and SomeClass.ObjectsActiveCount to know how many objects are still around at any point.

Another thing of note: C# classes do have destructors, contrary to popular belief. It has no delete keyword because of the Garbage Collector, and there’s little management to do for memory, but there’s still a possibility of using a destructor.

Worst way to do a sum

I’m dealing with some seriously bad code. It’s sort of like this.

Suppose you need to add two integers in C:

    int sum(int x, int y)
    {
        return x+y;
    }

Let’s not even consider nastiness like int limits, just a plain sum that works. That above is the sane way. That’s how you work. You do a single, tiny function that does a single job well.

This is the legacy I’m dealing with:

    //Declared globally
    int sum1 = /* a value */;
    int sum2 = /* another value */;
    int sum; /* the result */
    sumx(); /* execution */
    //...
    void sumx()
    {
        sum = sum1+sum2;
    }

Technically, it works. Same result. What’s the difference? Maintainability.

Simple C# Serialization

(Kudos if you noticed the alliterated title)
(Edit: this is an old article I never published. Until now! I hope it serves as a nice introduction to beginners).

Serialization is a thing I had (until recently) left untouched. For too long. Well, no more. Here are the basics.

What is serialization?
Simply put, it’s taking an object’s value(s) and writing them to a file (or a buffer, but I’m not covering that here) for transmission or storage.

What is deserialization?
It’s the reverse, building an object from a file (or buffer).

Why serialize?
Serialization can be used for various reasons, such as transmitting data to another computer or storing it. Storage could potentially be done with a database, but even something portable like SQLite is another thing to maintain, whereas for minimal needs, serialization offers quick and dirty clean storage for later use. For example, I’m using it for storing a few sets of parameters for batch processing.

Here’s how. I will be using the simplest form of XML serialization (that is, writing to, and naturally reading from XML), not Soap, but with the very vanilla System.Xml.Serialization namespace.

First, add System.Xml to your project’s references.

Now, we’ll design the basic class we want to serialize. First, the class without the serialization attributes:

public class ClientInfo
{
    public string ClientName { get; set; }
    public int ClientId { get; set; }
    public DateTime ProcessTime { get; set; }

    public ClientInfo (string clientName, int clientId)
    {
        ClientName = clientName;
        ClientId = clientId;
    }
}

To serialize, we’ll need the proper namespace, so add:

using System.Xml.Serialization;

in your using block at the top.

Next, we’ll decide what we want to serialize. Let’s say ClientName and ClientId, but ProcessTime shouldn’t be serialized at all (for some reason. Hey, I just needed the example).

So, we’ll need to tell the compiler that the class is serializable, simply by adding the attribute above the class declaration:

[Serializable]
public class ClientInfo
{/...

By default, all fields become serializable. Let’s specify the field to ignore appropriately:

    public string ClientName { get; set; }
    public int ClientId { get; set; }
    [XmlIgnore] //Tells C# to forget about that value for serialization
    public DateTime ProcessTime { get; set; }

Serialization also requires a default constructor. And the nice thing is that it does not have to be public, so your class logic can remain the same from outside (i.e. no default instantiation if you don’t want it):

    private ClientInfo()
    { }

The final result:

using System.Xml.Serialization;

[Serializable]
public class ClientInfo
{
    public string ClientName { get; set; }
    public int ClientId { get; set; }
    [XmlIgnore]
    public DateTime ProcessTime { get; set; }

    public ClientInfo (string clientName, int clientId)
    {
        ClientName = clientName;
        ClientId = clientId;
    }

    private ClientInfo()
    { }
}

And we’re done for that part! Now, suppose you want to serialize that into an Xml file. Use a function like so:

public static bool SaveConfig(ClientInfo clientInfo, string filePath)
{
    bool success = false;
    using (FileStream flStream = new FileStream(filePath, FileMode.Create, FileAccess.Write))
    {
        try
        {
            XmlSerializer xmlSerializer = new XmlSerializer(typeof(List));
            xmlSerializer.Serialize(flStream, clientInfo);
            success = true;
        }
        //do add proper handling of possible stream exceptions here
        finally
        {
            flStream.Close();
        }
    }
    return success;
}

And reading, essentially taking the XML class and making it into an object is just as easy, it’s called deserialization:

public ClientInfo LoadConfig(string filePath)
{
    if (!File.Exists(filePath))
        return null; //Or ClientInfo.Default if you made one

    ClientInfo clientInfo = null;
    using (FileStream flStream = new FileStream(destFileName, FileMode.Open, FileAccess.Read))
    {
        try
        {
            XmlSerializer xmlSerializer = new XmlSerializer(typeof(ClientInfo));
            clientInfo = xmlSerializer.Deserialize(flStream) as ClientInfo;
        }
        //do add proper handling of possible stream exceptions here
        finally
        {
            flStream.Close();
        }
    }
    return clientInfo;
}

This is just the tip of the iceberg. You can serialize/deserialize sub-objects, collections, etc. This is very useful for reading and writing back. And of course if you need to serialize/deserialize something large, there are better ways, like binary serialization!

Format versus localization

As fun as localization can be in .NET, sometimes you can struggle with it. I actually pity the American developer who will most likely code in something close to the Invariant culture and not know how un-portable his application will be.

For example, some (most) cultures use a decimal point, but others (like mine) use a decimal comma. So when you’re parsing an entry that’s in one culture (with decimal point), but your program runs another (with decimal comma), you get an error.

What you should do is define a format based on the input, and use that:

private static NumberFormatInfo FloatFormatInfo = new NumberFormatInfo()
{
    NegativeSign = "-",
    NumberDecimalSeparator = "."
};
private static NumberStyles FloatStyle = NumberStyles.AllowDecimalPoint |
                          NumberStyles.AllowLeadingSign;
//...
    float.Parse(textInput, FloatStyle, FloatFormatInfo, out _resultFloat);

(Or TryParse, depending). That’s the full control approach.

However, if you’re working against a library you can’t really change and need a quick fix, put this in your program:

System.Threading.Thread.CurrentThread.CurrentCulture = CultureInfo.InvariantCulture;

Put this in your Main. Remember that it’s a hack.

LINQ: working with pairs of items in a list

I’m learning about LINQ (I’ve been in a .NET vacuum due to work, so I need to catch up).

One of the things I do often with my current language tools is work on operations on sequential pairs in a list. LINQ makes that incredibly compact with Zip and Skip. I just don’t like the name “Zip” for this (too many things called Zip), so I made my own extension:

public static Extensions
{
    public static TResult[] WithNext<T, TResult>
        (this T[] source, Func<T, T, TResult> operation)
    {
        return source.Zip(source.Skip(1), operation).ToArray();
    }
}

Example of usage:

DateTime[] dts = // get a list of DateTimes.
TimeSpan diffs = dts.WithNext((x,y) => y - x);

That’s it, give it a list of DateTimes, get the difference between each (as TimeSpans). Final array is 1 element shorter. If the original list is 0 or 1 elements long, Zip is smart enough to return an empty set.

Generic EventArgs

It’s around the web, and it’s just too simple to avoid.

I’m talking of course about a generic EventArgs. When you have an event you need to fire and it should carry some argument(s), but you don’t want to commit to a full implementation of a custom EventArgs, you can use this handy technique to make a generic version of EventArgs:

Here is my version of it (for posterity and such):

public class EventArgs<T> : EventArgs
{
    public EventArgs(T value)
    {
        Value = value;
    }
    public T Value { get; private set; }
    public new static readonly EventArgs<T> Empty = 
        new EventArgs<T>(default(T));
}

That’s about as short as classes get! You should take the time to document it to give it a seamless, .NET-looking documentation when it comes up in Intellisense.

In the class that will use the event, we first need an event handler like this:

public event EventHandler<EventArgs<T>> MyEvent;

I put a T up there because at that point T can be any available type (from the mighty power of generics!), such as int, string, or a class. I use it mostly for text messages for certain events:

public event EventHandler<EventArgs<string>> MessageSent;

Next, prepare to invoke it. You don’t want to Invoke that by hand all the time, so use a function to cover that up:

private void InvokeMessageSent(string message)
{
    var handler = MessageSent;
    if (handler != null) handler(this, new EventArgs<string>(message));
}

And you’re done! Next time you want to fire that event, just do this:

InvokeMessageSent("Warning, I'm sending a message!");

The class which listens for this event will need to register that event to be ready to handle it:

var MyObject = new MyClass();
MyObject.MessageSent += new EventHandler<EventArgs<string>>(MessageSent);

Or simpler with implicit typing:

MyObject.MessageSent += MessageSent;