When a Standard Exists, Use It!

When a Standard Exists, Use It!

There are a lot of challenging and exciting problems in software engineering. Whether building a new GUI for a client or engineering a bare-metal high-performance simulation, there are opportunities to accelerate your development by applying standards.

Standards, in this sense, aren't necessarily just ISO-style standards. They can be conventions and defaults as well. Even when these are not 100% of what you might personally choose, leveraging them can be a powerful tool in your application development mindset. Essentially, it comes down to leveraging existing work as a force multiplier for your development efforts.

Standards Reduce Bugs

One standard I always insist on leveraging is the system of SI units. Not only does it make the math more manageable, it means that I can document interfaces less while having more confidence in their implementation. Take, for instance, an API for player position based on Imperial units:

// A Real API. Names changed to protect the innocent.
class ImperialPlayer
{
	public:
		double getXPositionFt() const;
		double getXPositionMeters() const;
		
		double getYPositionFt() const;
		double getYPositionMeters() const;

		double getXVelocityMPH() const;
		double getXVelocityFtPerSecond() const;
		
		double getYVelocityMPH() const;
		double getYVelocityFtPerSecond() const;
}

void PlayerFunction(double imperialXPosition, double imperialXVelocity)
{
	// Did we grab velocity in ft per second or mph?
	auto xPositionAtTime = imperialXVelocity*1.46667*deltaTime + 
	                       imperialXPosition;
	...
}

Now, consider what this API would look like when based on SI units:

class SIPlayer
{
	double getXPosition();
	double getYPosition();
	double getXVelocity();
	double getYVelocity();
}

void PlayerFunction(double siXPosition, double siXVelocity)
{
	// No doubt this is correct.
	auto xPositionAtTime = siXVelocity*deltaTime + siXPosition;
	...
}

We can reason, without documentation, that positions are in Meters and velocity is Meters/Second. Both the Position and Velocity are directly relatable. (No conversions required!) Not only does the SI standard make for a smaller API, it makes it less likely that the API is misused. When units are known throughout a system, conversion need only happen at a GUI level.

Case Study

On September 23, 1999, Lockheed Martin lost a $125 million Mars Climate Orbiter because of a units conversion error. The Lockheed Martin engineering team's ground-based software produced output in non-SI units of pound-force seconds (lbf·s) instead of the SI units of newton-seconds (N·s). (The use of SI units was specified in the contract between NASA and Lockheed.) While testing and other practices can help catch these errors, would it not be better to have a universally mandated standard within the system?

Standards Improve Tooling

There was a time when software teams published software coding style guides. These guides were lengthy, opinionated, and often under-utilized tomes of rules conjured up by a software team. Their purpose was noble: Make code more maintainable and less bug-prone by suggesting acceptable coding practices, formats, and aesthetics. Unfortunately, they were also hard to follow.

Modern software teams should abandon such guides and, instead, rely on standards. Now, modern language ecosystems are full of utilities to automate and enforce code style. Tools such as clang-format and clang-tidy utilize industry-best-practices to scrub code. Further, they can be incorporated into modern CI/CD or DevSecOps pipelines by using these tools. The use of these types of standards-enforcing applications provides enforcement, education, and consistency across a codebase. However, I would go further: While many of these tools offer customization options, use one of their default settings!

Il meglio è l'inimico del bene

Do not fall into the trap of striving for the perfect solution when you have a good solution. (Especially when building an MVP.) Once a system is in place, it can be refined. However, you may find that you don't need all of the custom features you first thought would benefit the software.

Summary

Are you writing a test plan? Look for an IEEE-standard template.

Are you serializing data? Look for an appropriate de-facto standard.

Are you compressing data? Start with zlib.

Need to design a UI? There's a Microsoft Style Guide and an Apple Style Guide for that.

In any software project, there is new code that must be authored to get the job done. Accelerate your development by leveraging standards. There will be times when you need to go your own way and blaze new ground. But whether a formal standard or a de facto standard, start with prior art.



John Far​rier
AUTHOR

John Far​rier

Chief Executive Officer

CEO, Hellebore Consulting Group. John has over 20 years of experience in building software for DoD organizations, leading organizational change, and building strong cultures.

Like what you hear?

Join forces with Hellebore today!

Contact Us