Contextive READMEContextive is a Visual Studio Code extension to assist developers in environments with a complex domain or project specific language, where words have a special meaning in the context of the project. It should help new team members get up to speed more quickly in understanding domain-specific terms. By storing the term definitions in your repository, and surfacing the definitions as you work on the code, it encourages the use of the domain-specific terms in your code, and regularly updating the definitions as the team's understanding evolves. Getting StartedUse the This sample file illustrates the use of Contextive by defining the terms used in the definitions file yml structure itself. You can hover over the name of the terms in the file to see Contextive in action (see the sample image above). You should delete the sample definitions and replace them with your own. PhilosophyContextive is inspired by the concept of the Ubiquitous Language from the practice of Domain Driven Design (DDD) and should 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. Features
ExamplesIn the following sections, examples are drawn from the Cargo domain, as explored by Eric Evans in his seminal work on DDD - Domain Driven Design: Tackling Complexity in the Heart of Software. The usage examples are quoted or inspired by sample conversations in the book - ideally, your usage examples should be exact sentences as said by your domain experts. The following Contextive definitions file was used to generate all screenshots/scenarios below:
Combined WordsFor the hover display, Contextive is able to identify the use of defined terms in combined words - where terms are combined using Suffixes and PrefixesIt's quite common to combine a term from your language, such as Combining two (or more) termsIt's also common to end up with code elements (classes, variables or methods) that combine two or more terms from your language, such as Multi-word termsSometimes, the combined term needs its own unique definition - just add it to your definitions file, and Contextive will work out that the more precise match is the one you want, decluttering your hover panel. It can be added to your definitions file as either separate words (e.g. This also now works for Plural WordsContextive can detect a defined term even when it is defined in the singular and used in the plural. Coming Soon: Ability to detect a defined term when it is defined in the plural and used in the singular, and when individual words in a multi-word term are pluralised or singularised. Term AliasesContextive supports defining a list of aliases for a given term. These can be acronyms or just alternative words that are sometimes used interchangeably. For example, in the cargo domain above, When hovering over the word Multiline YAMLAs some of the fields in the definitions file could have long text, it may be helpful to use multi-line yaml. Because the fields are interpreted as markdown, there are some special considerations to be aware of. The site https://yaml-multiline.info/ is a great resource for multi-line yaml fields. The following common scenarios are more fully explored in the multiline sample file and apply to all fields, but are most likely useful for the Multiline with Line BreakIf a definition (or domain vision statement) is quite long, and you would like to include linebreaks (but not new paragraphs), you need to use one of the yaml multi-line options that ensures at least one newline is parsed, AND to render a markdown linebreak you need to add two
Renders to: Multiline with New ParagraphTo achieve a new paragraph, use a yaml option that parses multiple newlines, e.g.:
Renders to: Multiline in No Newline in HoverSometimes you may want to break over multiple lines to make it easier to read the raw yaml, but don't want the newlines to appear in the hover. In this case, just don't use any Markdown linebreak or new para features. e.g.:
Renders to: The line will still wrap according to the width of the hover panel. Smart Auto-CompleteAs the terms added to the auto-complete are from a definitions file, not from your code symbols, the auto-complete will work in any file of any language - including documentation, such as markdown. To ensure it's useful in a variety of scenarios, it includes a number of options to fit your required format:
The auto-complete options will adjust as you type - e.g. after typing a single lower-case letter, only Repository OrganisationContextive is designed to work with a variety of repository organisation schemes: Single Bounded Context, Multiple RepositoriesWhen a single context is comprised of services, each with their own repository, it's not ideal to have to maintain a copy of the context's language definitions in each repository. To facilitate this pattern, Contextive recommends storing the terms only once, in a central/common repository, and using native package management facilities to distribute the definitions file as part of any common code packages. For package managers that store the packages within the workspace, simply set See https://github.com/dev-cycles/contextive-demo-go-service for an example of this in action using Multiple Bounded Contexts, Repository per ContextThis is the simplest option - all you need to do is define the terms for that context in the relevant repository. Multiple Bounded Contexts, Single Repository, Single-Root (Monorepo)For projects utilising a monorepo it's not uncommon to have code relating to multiple bounded contexts in the same repository. At this time, Contextive tracks all definitions in the same file. Each context has a This is particularly helpful if the same term (e.g. a common term, like Each context has optional properties Given the definitions file above, and a folder structure like so:
Contextive will match the files to the path glob configurations. When hovering over When hovering over Multiple Bounded Contexts, Multi-Root, Shared Definitions FileVisual Studio Code supports a multi-root workspace configuration which allows separate folders to be selected as 'roots' of a workspace. Contextive supports this configuration as long as the definitions for all roots are in a shared file. (Support for separate files per root is a future enhancement.) The Contextive definitions file is located at The If you'd like to store the definitions file in a different location, the appropriate settings location to use is the Coming Soon
Extension SettingsThis extension contributes the following settings:
Known Issues
|