A GLOSSARY file is a conventional file like a README or LICENSE file, which you can include in a code repository to document the terminology and abbreviations used in the project.

For example, you might use a loosely structured format like a GLOSSARY.txt or GLOSSARY.md:

# Terminology

- code point — an index in a character set

- code unit — the unit of storage of a character encoding

# Abbreviations

- CCC — Cartesian closed category
- decl — declaration
- NS — namespace
- SCC — strongly-connected component

Or you might use a more structured machine-readable format, like a GLOSSARY.yaml:

terms:
  code point: an index in a character set
  code unit: the unit of storage of a character encoding

abbrs:
  CCC: |
    Cartesian closed category
  decl: declaration
  NS: namespace
  SCC: |
    strongly-connected component

I don’t mean to prescribe any particular format here, the idea is that this is just a documentation convention. It could be used as the basis of tooling if you want, but is nevertheless valuable without it.

At my first full-time job, I wrote a linter for our codebase which would check some of our basic house style rules that were not enforced by other third-party lint tools such as HLint. For example, my linter would check that line lengths didn’t exceed 80 columns, and advise reducing the nesting of deeply indented code, with various exceptions for commentary and testing.

On a whim, I added a feature that would check our naming conventions, too. It would split up each name in the code and check that the parts conformed to the naming rules; one such rule was that each part should be either a dictionary word, or a “known abbreviation”. For instance, inheritEnv was allowed because inherit is a dictionary word and env was defined in our glossary list, but inhEnv or inheritEnvt would not be.

This had a couple of nice consequences:

• We needed to vet the abbreviations that were already used in the code, and decide which were worth keeping. For example, we chose to allow common general-purpose and domain-specific abbreviations such as msg and lhs, as well as some project-specific ones widely used throughout the codebase such as Fqn for “fully-qualified name”; but we chose to disallow others that weren’t adding value, like str and fn.

• When we used a new abbreviation, we would get a warning about it, so we had to decide whether it was worth adding. This gave us a simple, unobtrusive reminder to keep up a certain standard of clarity in naming.