The Professional Developer Series #1 – Source Control Discipline

I believe that every developer is using some kind of source control software. Be it distributed source control like Git, Mercurial etc. or centralized ones like SVN, TFVC and Perforce. If you are not using source control (why?) or if you don’t know what I am talking about, please read this – Why should I use version control?.

Proper use of source control software is essential to software development and yet few software shops practice it correctly. This is because writing code is seen as the primary task and correctly managing the process of writing code is a secondary concern. This prioritization is correct to some extent and does make business sense. You need to ship on time and ship with new features. There’s no luxury to ask the customer to wait just because you want to sharpen your metaphorical developer axe. Usually, a developer will finish working on a feature, check in all the files that have been changed and then forget about it.

Granted, in most enterprise development environments, where time is limited and developer focus is on feature delivery and bug fixes, you don’t normally have the luxury to worry about readability, loose coupling, maintainability and performance of your code when the business user is breathing down your neck to release the next feature. But let me show you why it is worthwhile to focus on what you check in and how it will save you time in the long run.

What really is source code? Sure we have all these files in a project which compile to form the final executable. But what are those files? I find it important to understand what files form your source code and more importantly, the nature of those files.

When it comes to source control, I divide the files into the following categories:

  • Source code files
  • Configuration files
  • Generated files or Designer files
  • Third party libraries
  • User specific settings
  • Build output

Source code files

The heart of any software project and will mostly use the project’s primary language like C#, Java, etc. These files should obviously be checked into source control and you will most likely have a compilation error if any files were missing. This may happen if you add a new file to the project and forget to check it into source control and your fellow developer checks out the latest version and will face a compilation error due to a missing file.

Configuration files

Configuration files should normally be in source control but with one caveat, any file that has user specific configuration should not be checked in to the source control. These files generally have runtime specific values like connection strings, credentials etc.

Auto Generated or Designer files

These are files like *.designer.cs, WCF service reference classes, Entity Framework files generated by Visual Studio, etc.

Even though these files are generated by a tool, they should be checked in to the source control system. The main difference between these and build output is that these files are generated not produced by the build tool but are rather the output of third party tools, the IDE or extensions etc.

Since these are not produced by the build process itself, for the compiler they are as good as source code and should be treated as such and checked into source control.

Third party libraries

Third party libraries are not part of the application source code but they should be checked in to source control as they are external dependencies and come under the category of “anything required to build software.”

However, I should mention that the recent trend is to not check these files in to source control as package managers like npm, nuget, etc are becoming more ubiquitous and reliable. The current trend favors getting these at build time from their package sources. You can go both ways with this, but make sure that if you choose to not check these in, at least host a package server within your enterprise.  This way if after 5 years, nuget or npm repository goes down, your then legacy application will continue to build reliably.

User specific settings

These are your *.user file extensions. The extension makes it very easy to add these to source control ignore files like .gitignore.

User specific settings should by definition never be checked in to source control as they are user specific and cannot reside in a repository that is meant to be shared across the team. I have seen one too many bugs happen in production because a user specific setting made its way into the production build.

Build Output

Build output is the artifact that is finally produced by the build process although it may not necessarily be binary executable files i.e. bootstrap source code produces the finished bootstrap.css file which is not an executable but it would be considered as the build output of the bootstrap project. These should never be checked in to source control, but unfortunately this is something I have seen more often than I would like to believe.

The easiest way to detect if you have these checked in is if you run a build and see pending changes in your source control. That’s a clear red flag right there. You should not see a single byte of pending change in your source control when you build the project.

That’s all for this first article in The Professional Developer series. I hope to continue this series with interesting content on how to keep improving your skills as a developer 🙂