# TOML Configuration Practices This guide covers **TOML-specific configuration design patterns and organizational decisions**. For general guidance applicable to all languages, see the main [practices guide](practices.md). For cross-language formatting and visual presentation principles, see the [code style guide](style.md). For shared workflow guidance, see the [environment guide](environment.md), [validation guide](validation.md), [testing guide](tests.md), and [release guide](releases.md). ## Configuration Design - Prefer table arrays with `name` fields over proliferating custom subtables. This approach scales better and reduces configuration complexity. **❌ Avoid - custom subtables:** ``` toml [database] host = 'localhost' [database.primary] port = 5432 timeout = 30 [database.replica] port = 5433 timeout = 15 ``` **✅ Prefer - table arrays with name field:** ``` toml [[database]] name = 'primary' host = 'localhost' port = 5432 timeout = 30 [[database]] name = 'replica' host = 'localhost' port = 5433 timeout = 15 ``` - Apply nomenclature guidelines from the [nomenclature guide](nomenclature.md) to key and table names. Use Latin-derived words when they are the established norm in the domain. ## Key Naming Conventions - Use hyphens instead of underscores in key names for better ergonomics and visual clarity. **❌ Avoid:** ``` toml max_connections = 100 retry_count = 3 database_url = 'postgresql://localhost/db' ``` **✅ Prefer:** ``` toml max-connections = 100 retry-count = 3 database-url = 'postgresql://localhost/db' ``` - Follow the project's nomenclature patterns: - Use suffix patterns: `timeout-default`, `connections-maximum` - Use Latin-derived terms for consistency with the broader project - Group related keys with common prefixes: `server-host`, `server-port`, `server-timeout` ## Formatting Standards - Use single quotes for string values unless escapes are needed, in which case use double quotes. **✅ Prefer:** ``` toml name = 'example-service' pattern = 'user-.*' # Use double quotes when escapes are needed windows-path = "C:\\Program Files\\Example" ``` - Keep arrays and inline tables on single lines when they fit within reasonable length. For longer arrays, use multi-line format with trailing commas. **✅ Prefer:** ``` toml ports = [ 8080, 8443, 9090 ] server = { host = 'localhost', port = 8080, timeout = 30 } # Multi-line for longer arrays allowed-origins = [ 'https://example.com', 'https://api.example.com', ] ``` ## Configuration Organization - Group related configuration keys into logical sections with descriptive table names. **✅ Prefer:** ``` toml [server] host = 'localhost' port = 8080 max-connections = 100 timeout-default = 30 [database] url = 'postgresql://localhost/mydb' connections-maximum = 10 timeout-query = 15 [logging] level = 'INFO' file-path = '/var/log/myapp.log' rotation-size = '10MB' ``` - Use consistent patterns across configuration files in the project. - Document complex or non-obvious configuration choices with comments.