Contextive is a suite of tools to immerse developers in the language of their users' domains.
Contextive is inspired by the concept of the Ubiquitous Language from the practice of Domain Driven Design (DDD) and is intended to support ubiquitous language management practices on DDD projects.
Even if you're not using Domain Driven Design, Contextive should still be very helpful in any software project where it's important that developers are aligned on the meaning of terms.
By defining terms in a central definitions file, Contextive can surface definitions and usage examples in auto-complete suggestions & hover panels wherever the terms are used - in code (of any language across the stack), comments, config, and documentation (e.g. markdown).
The following list of features is a draft proposal of the vision at the start of the project. It's expected that the list will evolve as a prototype is developed and experimented with and lessons are learnt.
- Ubiquitous Language Definition & Storage:
- Classify terms as aggregates/entities, attributes, commands and events
- For each term, include a definition, and examples of usage in normal sentences
- Link terms to each other (e.g. commands to the aggregates/entities they apply to; events to the aggregates/entities that publish them)
- Define relationships between contexts (e.g. a Context Map definition)
- Store Ubiquitous Language term definitions in a file in the repository (e.g. yml format)
- Support a monorepo with multiple Bounded Contexts in one repo - identify which paths relate to each Bounded Context
- Support a Bounded Context distributed across multiple repos (#36)
- Support aliases of terms, hovering over the alias shows the term definition
- Add details of the alias in the hover
- Add ability to define an alias as deprecated and warn as such
- Support multiline domain vision statements, definitions and usage examples
- IDE Support
- Visual Studio Code
- Support single-root workspaces
- Support multi-root workspaces with a shared definitions file
- Support multi-root workspaces with a definitions file per root
- Visual Studio (2019/2022)
- Eclipse
- NetBeans
- JetBrains
- vim
- emacs
- Visual Studio Code
- Code-editing Features
- Show the term definitions & usage examples when hovering over the word in the editor
- Also when the word being hovered over is plural of the defined singular term
- Also when the word being hovered over is singular of the defined plural term
- Also when the combined word being hovered over is contains singular or plural of a word in a defined multi-word term
- Add Ubiquitous Language terms to the auto-complete list
- Codelens to identify the number of Ubiquitous Language terms in a method or class
- Problems/warnings if misuse of the Ubiquitous Language - e.g. use of Command/Event and aggregate in the same class or method name when they are not linked, or use of extra words next to an Aggregate that isn't defined
- In relevant places (e.g. hover), note the use of the term in other contexts to highlight the contrast and ensure clarity of which definition applies in the current context (e.g. 'THIS definition, NOT that other definition that you might have been thinking of')
- Show the term definitions & usage examples when hovering over the word in the editor
- Ubiquitous Language Management Features
- Go To term definition (right-click menu, keyboard shortcut)
- A UI widget to view the language terms in a TreeView and offer facilities for adding, updating & removing terms
- Make it easy to add terms to the Ubiquitous Language from existing code e.g. by highlighting and using the right-click menu
- Ubiquitous Language Sharing Features
- Render definitions into a human readable format - e.g. html, markdown etc.
- Sync definitions into a cloud storage, e.g. Notion database, or confluence page
- Above features might be well packaged as a CLI as well as extension features, for running in CI/CD
Open Visual Studio Code, launch the quick open (Ctrl+P) and then enter ext install devcycles.contextive. OR, search contextive in the extensions side-bar.
Visit the Contextive Marketplace page for details.
Check the extension README for usage instructions.
Coming soon!
If you have ideas for features or implementation, please open an issue to record your thoughts.
PRs welcome, but as things are evolving rapidly, a conversation before any major changes is probably worthwhile.
Key architectural decisions are tracked using ADRs (Architectural Decision Records) which can be found in the docs/adr folder. The MADR format is the current default.
Development is being done using Visual Studio Code Dev Containers. After cloning the repository and opening in Visual Studio Code, choose the "Reopen in Container" option to work in the dev environment. See the Visual Studio Code documentation for more details on setting up your docker environment.
The Contextive logo is based (with extreme gratitude!) on the Bibliophile image from https://undraw.co - an amazing resource of free images and illustrations.