Source Code Normalization and Diff/Merge Monday, November 3, 2008

Eclipse IDE and Resharper for Visual Studio both offer a feature which reorders type members and reformats source code based on a configurable coding style. They also offer the ability to share this code style (spacing, tabs, etc) among other developers. I call this reordering and style application source code normalization. Consider the following example from Resharper:

using System;

using System.Web.UI;
using System.IO;


namespace PrettyUrlWeb.js
{
    public partial class Search : Page
    {
        private string data2;

        public string Data2
        {
            get
            {
                return this.data2;
            }
        }

        protected void Page_Load(object sender, EventArgs e)
        {
            this.ImageButton1.ImageUrl = System.IO.File.ReadAllText("DATA.URL");
        }

        private int data0;
        private object data1;


        public int Data0
        {
            get{return this.data0;}
        }


        public Search()
        {
        }

        public enum DataModes
        {
            Good,
            Bad,
            Ugly
        }
    }
}

It is clear to see that this code file has been edited by several developers with differing code styles. If apply a code style (as they call it in Resharper) template such as the one I created and use often, the result would be something such as:

using System;
using System.IO;
using System.Web.UI;

namespace PrettyUrlWeb.js
{
    public partial class Search : Page
    {
        #region Constructors/Destructors

        public Search()
        {
        }

        #endregion

        #region Fields/Constants

        private int data0;
        private object data1;
        private string data2;

        #endregion

        #region Properties/Indexers/Events

        public int Data0
        {
            get
            {
                return this.data0;
            }
        }

        public string Data2
        {
            get
            {
                return this.data2;
            }
        }

        #endregion

        #region Methods/Operators

        protected void Page_Load(object sender, EventArgs e)
        {
            this.ImageButton1.ImageUrl = File.ReadAllText("DATA.URL");
        }

        #endregion

        #region Classes/Structs/Interfaces/Enums/Delegates

        public enum DataModes
        {
            Good,
            Bad,
            Ugly
        }

        #endregion
    }
}

An organization can define code reorder/style templates and publish them to developers. Before a developer checks in code edits, they should run the template against their changes to ensure the source code normalized.

There are several benefits to normalized source code: better visual appeal, easier reading and maintainability, ability to region code automatically, uniformity across the organization, and easier diff/merges. The last benefits deserves a bit more discussion.

When source code is normalized, it is becomes naturally easier to diff/merge changes. Lets look a very simple non-code related diff/merge situation. Here we have a list of names in a text file, stored in a source control repository:

Chris
Eric
David
Nick
Todd
Obie
Ryan
David
Rob
Daniel
Michael
Brendan

Now, lets say we need to edit this file, say to add "Heather" and "Kevin", remove "Michael", and change the first "David" to "Dave". The following shows the diff result after an edit of the original non-normalized data and arbitrary positioning of edits:

(Click images for a larger view.)

The following shows the diff result after an edit of an alphabetical ordered normalization of the original data and normalizing of the edits:

(Click images for a larger view.)

Even in this simple example, the normalized diff is easier to read; now scale this in your mind to complex code file and you can see the benefit of normalized source code for ease of diff/merge operations.