Skip to content

force push


TOML, maintainability, software engineering1 min read

Config files should be readable and editable by both humans and machines. What defines this? A format with a clear specification (for the machines to parse) and easy on the eyes/fingers (for humans to read and modify). There are a few popular options:

  • XML: Basically HTML - tricky to read and tricky to edit by hand. Diffs will be messy.
  • .INI: Several competing specifications, so really not even worth considering.
  • YAML: An improvement over XML in readability, but the whitespace-as-syntax might trip you up. GitHub Actions uses this for defining workflows, and tools like Dependabot and pre-commit read configurations from YAML files.
  • JSON: The de facto format for passing around data in webdev, with a dictionary-like syntax. Hope you like commas and braces.
  • TOML: A happy medium between human and machine readability. Used for specifying Rust project dependencies in Cargo.toml, and for Python project configs in pyproject.toml.

I reach for TOML if I have the choice.