GLOSSARY file is a conventional file like a
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
- 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
Or you might use a more structured machine-readable format, like a
code point: an index in a character set
code unit: the unit of storage of a character encoding
Cartesian closed category
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
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
lhs, as well as some project-specific ones widely used throughout the codebase such as
Fqnfor “fully-qualified name”; but we chose to disallow others that weren’t adding value, like
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.