package module
Version: v1.0.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Mar 25, 2019 License: MIT Imports: 0 Imported by: 0



Go tools to assist with "programming by contract"


All prerequisites will be handled automatically provide this library is checked out using the command:

go get github.com/klassen-software-solutions/gocontract.git


This library contains items useful in coding based on Design by Contract. Specifically it provides the ability to add checks on preconditions, postconditions, middle conditions, and invariants in an expressive manner.

API Documentation

To terminate or not to terminate?

A common debate in programming by contract is what action should be taken when a contract condition fails. We have taken the opinion that condition failures will write an error message to the standard error device, and then exit the program via os.Exit(1). (This is largely following the advice of Ferguson, Schneier, and Kohno in their book Cryptography Engineering. It was that book as well as Schneier's book Click Here to Kill Everybody that were the primary influencers in our decision to create this library.)

In addition we chose that the condition checks would always take place regardless of whether your code is compiled in debug mode or production mode.

Customizing the actions

At present we provide no facility for customizing what happens on a failed condition check. However, if you really want to do it differently, feel free to take this code and modify it for your own purposes.

The key method that you need to change is performConditionChecks and is found in condition.go. It's use is common to all the conditions so modifying that one method will affect them all.

Using this library
Condition checks

All the condition types, Preconditions, Conditions, and Postconditions work the same way. In fact all three do the same thing except for slight differences in the message that is reported. The are presented as three methods only to help document the intent.

Specifically, the intent is that preconditions are checked at or near the start of a method, postconditions at or near the end of a method, and conditions anywhere in between. Each of them takes any number of expressions returning boolean values. If any of the expressions returns false, a suitable message is produced on the standard error device, and the program is halted.

For example, the following could be used to check assumptions at the start of a given method.

type MyStats struct {
    MinValueSeen, MaxValueSeen, AverageValueSeen int
    Count uint

func (s *MyStats) AddAValue(value int) {
    oldCount := s.Count
        s.MinValueSeen <= s.AverageValueSeen,
        s.AverageValueSeen <= s.MaxValueSeen
    // ... update the stats ...
        s.MinValueSeen <= value,
        value <= s.MaxValueSeen,
        s.Count = oldCount + 1

You could add a defer in front of the postconditions call, but typically we don't on the assumption that the postconditions are only true if no error occurs. Of course you could have two sets of post-conditions, one for a valid exit and one for an error exit, but we have never bothered to do that in our own code.

An invariant is similar except that you don't give it an expression, you simply call the Check method to see if the invariant has changed. Note: Our implementation of an invariant does not actually check for inequality. Rather its computes a hash based on the %v representation of the object and check if that hash has changed. This is not technically a full check of the invariant, but it is generally good enough to see if something has changed.

Very often an invariant is used to ensure that a method that should not change an object has indeed not changed the object. This could look like the following:

func (s *MyStats) PrintTheStats() {
    inv := contract.NewInvariant(s)
    defer inv.Check()
    // ... print out the representation of the stats ...

Note the user of defer to ensure the variant is always checked. You could leave this out if you so desire, but generally an invariant should be invariant regardless of how the method exits.


If you wish to make changes to this library that you believe will be useful to others, you can contribute to the project. If you do, there are a number of policies you should follow:

  • Check the issues to see if there are already similar bug reports or enhancements.
  • Feel free to add bug reports and enhancements at any time.
  • Don't work on things that are not part of an approved project.
  • Don't create projects - they are only created the by owner.
  • Projects are created based on conversations on the wiki.
  • Feel free to initiate or join conversations on the wiki.
  • Follow our Go Coding Standards.



Package gocontract is the top-level project for the GO contract utilities. The version and license for the library are found in this package, but all other code is found in the sub-packages.



View Source
const License = `` /* 1082-byte string literal not displayed */

License contains the license text of this library.

View Source
const Version = "v1.0.0"

Version contains the current version number of this library.


This section is empty.


This section is empty.


This section is empty.


Path Synopsis
Package contract provides support for runtime "Programming by Contract" checks.
Package contract provides support for runtime "Programming by Contract" checks.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL