A Software Engineering Process Standard

A very colorful froggy

When you standardize the form for consistency, the parts are more likely to fit into place perfectly.

The reality of the world of software design, implementation, and maintenance is that these systems can become quite vast, both in complexity and extent. And developers move about: you will bring in new people, or you’ll move your experienced personnel to different roles. Sitting at a new box (I use this term when referring to a computer) and being confronted with a new codebase, a strange toolset, and a new filesystem organization, can mean days of wasted time trying to sort out what’s going on. What helps here, is to standardize as much as possible, in many aspects and on many levels. Consistency helps to breed quick comprehension and make mistakes stand out.
Here is The Standard as proposed by James Hurst and evolved over [many] years of experience.

Cleaning Up

Put a command-line script within your project directory that cleans up any build-product files. For a Microsoft Visual Studio solution, put this script within the solution’s root folder. This can be either a Powershell script – in which case it should be named Clean.ps1, or else a DOS batch file named Clean.bat or Clean.cmd. Assuming this is a Powershell script, make it such that you can call it from within the folder in which it’s located, thus: Invoke-Expression .\Clean.ps1 , and also from another folder. For example, if you have a folder that contains all of your projects, and within that root folder you have a script called CleanAll.ps1, you should be able to have that script call the Clean.ps1 script within each of your projects – thus cleaning up all of your software projects with one command.

The purpose of your Clean script is to clean out all files that are produced by your build process, such that the files that are left and the ones you would want to include within your source-control system. In the case of a Visual Studio solution, this script should completely delete the bin folder, and the obj folder. If you’re using JetBrains ReSharper, then you may want to delete the _ReSharper.YourSolution folder.

Automated Testing

Put at the top of your test source-code file ALL requirements that must be satisfied for your tests to run successfully. Don’t leave your fellow developers thrashing about trying to figure out how to make your tests work. If it needs to write something to the filesystem, say this – and where. If a web-service or database is used, say so. Are admin privileges needed? Does it require access to the public Internet? Does it expect to be run only on 64-bit systems? You are writing a contract, in the legal sense — be concise and precise. You don’t have to be pedantic or write a tutorial here – just make a complete list. Define any ambiguous terms, and do a complete job of it. It is unprofessional to fail to do this.

Automated-Test Filesystem Location:

For running automated unit-tests, or rather integration or system tests if that is your preferred vernacular for tests that access the filesystem, there can be merit in standardizing upon a default path for these tests to use, if some other path is not necessary.

When your unit-tests use the local filesystem, base them under this location:

C:\Tests

For each distinct application or development effort, produce a separate folder underneath that. For example..

C:\Tests\MyWordProcessor

The advantages are minor, but useful. You will be more likely to recognize at a glance where that folder comes from, when scanning your filesystem. You don’t have to spend more than a moment’s thought to know where to go to examine or delete that folder. And if you’re an IT dept. setting up a box with limited permissions for your developers or testers, you can create this folder and give the appropriate permissions, and know that this need is being met.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s