Messy Source Code Repositories

It goes without saying, a messy work-space impacts the ability to be organized and perform well. Everyone has messes, but in a common space organizing and maintaining that cleanliness is essential.

When and Why?

This process should be started immediately in any organization because it will save time and money increasing the pace of development. Rarely in a company is there an opportunity for a software re-write. Technical debt is often put off. The time to make the corrections is every day and then continuously (aka continuous improvement). New processes are typically put into place to manage the extensive mess. These processes potentially only add a layer on top of the existing mess and therefore are complex and generally lack patterns. This must be corrected at the foundation.

Figure 1. A hard copy mess with many similarities to unkept repositories.

Typical Findings

In a comprehensive inventory of messy source code repositories common findings include:

File System

• Extensive irregular source code filing
• More than a few empty or junk (new and unchanged) source code projects, solutions, and directories
• Committed bin and obj directories and files
• Intermingled mixed platform and language source code
• Mixed documentation and source code
• Inconsistent and duplicate storage of 3rd party code and binaries

Source Code

*Restricted to .NET high-level organizational patterns only.

• Namespaces not consistent with location
• Namespaces missing
• Class names not consistent with file name
• Multiple classes in the same file
• Source code files missing from projects
• Inconsistent assembly and project reference patterns
• Ad hock solution creation and composition
• Assembly name/project name mismatch

Starting Recommendation

This is just a start. A starting place must be carved out before the next layer of organization, standardization and patterns can be addressed. These recommendations target only high-level organizational patterns and standards.

Step 1

1. Define, implement and enforce a pattern for source code storage
2. Separate source code based on platform and language (non .Net vs. others)
3. Separate documentation and diagrams
4. Remove any compiled code and add ignore statements to source control for those files and directories
5. Collapse, consolidate and organize 3rd party code and binaries
6. Remove all unused projects, solutions, files, and folders

Step 2

1. Define, implement and enforce a solution (.sln) pattern
2. Install and enforce the usage of JetBrains ReSharper for all .NETdevelopers
3. Fix project properties to match assembly name and namespace
4. Fix namespaces to match location
5. Fix class names that do not match the file name
6. Define and standardize assembly reference policies
7. Clean and standardize all AssemblyInfo.cs code files

Next Steps

After completion of the first 2 steps attention can turn to the code itself. In the next steps it’s important to standardize using patterns. This includes class and project structure, reduction in code duplication, collapsing of projects, namespace cleaning and standardization, removal of legacy or unused code blocks, removal of unused references, standardization of comments, etc. These steps are necessary steps to get to a cleaner working base. A clean working base will accelerate the integration of new code, designs, patterns, bug fixes, unit testing, and ramp-up time for new engineers.