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

# 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:

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

  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: