gocontracts
A Go tool that automatically generates pre- and post-condition checks from function descriptions to implement design-by-contract.
What is gocontracts?
gocontracts is a design-by-contract tool for Go that synchronizes contract specifications in documentation with runtime checks in code. It parses function descriptions to generate and update pre-condition, post-condition, and preamble code blocks, ensuring contracts are both documented and enforced. This approach helps maintain consistency between documentation and implementation.
Go developers and teams implementing formal design-by-contract methodologies in their codebases, particularly those needing automated synchronization of documented invariants with actual runtime checks.
Developers choose gocontracts because it uniquely synchronizes contract documentation with generated code, avoiding drift between specs and implementation. Unlike alternatives, it supports condition labels, initialization statements, state transitions via preambles, and build-time toggling, all while emphasizing logical invariants over input validation.
Overview
A tool for design-by-contract in Go
Use Cases
Best For
- Automatically generating runtime checks from contract specifications written in Go function docstrings
- Maintaining synchronization between documented function contracts and actual code implementations
- Implementing state transition contracts that require capturing pre-execution state via preamble blocks
- Conditionally enabling or disabling contract families across different environments using build tags
- Adding descriptive labels to contract conditions for clearer documentation and panic messages
- Enforcing logical function invariants (rather than input validation) with panic-based failure handling
Not Ideal For
- Projects where input validation should return user-friendly errors instead of panicking
- Teams needing automatic import management for conditions that use external packages
- Codebases requiring syntax or semantic validation of contract conditions before code insertion
- Developers looking for invariant checks on structs or across multiple functions (not yet supported)
Pros & Cons
Pros
Parses function docstrings to generate and update pre-condition, post-condition, and preamble code blocks automatically, reducing manual coding effort.
Ensures contract specifications in documentation are always reflected in runtime checks, preventing drift between specs and implementation as highlighted in the README.
Allows capturing pre-execution state via preamble blocks for contracts that depend on before/after comparisons, enabling formal state transition checks.
Supports conditional enabling of contracts using build tags and boolean constants, allowing flexible deployment across testing and production environments.
Cons
Does not check for syntax errors or undefined variables in conditions, inserting code as-is which can lead to runtime panics if conditions are malformed, as admitted in the README.
Requires developers to manually import packages used in contract conditions, since the tool does not manage dependencies, adding extra overhead.
Condition labels are limited to a specific character set [a-zA-Z0-9_;.\-=' ], which may not cover all naming conventions and could cause ambiguity in documentation.
Frequently Asked Questions
Related Projects
gotestsAutomatically generate Go test boilerplate from your source code.
xgenXSD (XML Schema Definition) parser and Go/C/Java/Rust/TypeScript code generator
hasgoHaskell-flavoured functions for Go :smiley:
gonericsGenerics for go
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.