runc/style.md

# Style and conventions

## Traditionally hex settings should use JSON integers, not JSON strings

For example, [`"classID": 1048577`][class-id] instead of `"classID": "0x100001"`.
The config JSON isn't enough of a UI to be worth jumping through string <-> integer hoops to support an 0x… form ([source][integer-over-hex]).

## Constant names should keep redundant prefixes

For example, `CAP_KILL` instead of `KILL` in [**`linux.capabilities`**][capabilities]).
The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]).

## Optional settings should have pointer Go types

So we have a consistent way to identify unset values ([source][optional-pointer]).

[capabilities]: config-linux.md#capabilities
[class-id]: runtime-config-linux.md#network
[integer-over-hex]: https://github.com/opencontainers/specs/pull/267#discussion_r48360013
[keep-prefix]: https://github.com/opencontainers/specs/pull/159#issuecomment-138728337
[optional-pointer]: https://github.com/opencontainers/specs/pull/233#discussion_r47829711
style: Collect established styles in a discoverable location So we have something to cite to avoid rehashing established decisions. Provide some motivation and links to the backing discussion so folks can re-open these if they have new information that wasn't covered in the original decision. Like the glossary (18734986, glossary: Provide a quick overview of important terms, 2015-08-11, #107), I've used subsection titles for each entry to get link anchors. Signed-off-by: W. Trevor King <wking@tremily.us> 2015-12-30 12:31:10 +08:00			`# Style and conventions`

			`## Traditionally hex settings should use JSON integers, not JSON strings`

			For example, [`"classID": 1048577`][class-id] instead of `"classID": "0x100001"`.
style: remove unicode character pandoc/LaTeX is not happy with this shady character. ``` ! Package inputenc Error: Unicode char \u8:↔ not set up for use with LaTeX. ``` Signed-off-by: Vincent Batts <vbatts@hashbangbash.com> 2016-01-15 04:18:52 +08:00			`The config JSON isn't enough of a UI to be worth jumping through string <-> integer hoops to support an 0x… form ([source][integer-over-hex]).`
style: Collect established styles in a discoverable location So we have something to cite to avoid rehashing established decisions. Provide some motivation and links to the backing discussion so folks can re-open these if they have new information that wasn't covered in the original decision. Like the glossary (18734986, glossary: Provide a quick overview of important terms, 2015-08-11, #107), I've used subsection titles for each entry to get link anchors. Signed-off-by: W. Trevor King <wking@tremily.us> 2015-12-30 12:31:10 +08:00
			`## Constant names should keep redundant prefixes`

			For example, `CAP_KILL` instead of `KILL` in [`linux.capabilities`][capabilities]).
			`The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]).`

			`## Optional settings should have pointer Go types`

			`So we have a consistent way to identify unset values ([source][optional-pointer]).`

			`[capabilities]: config-linux.md#capabilities`
			`[class-id]: runtime-config-linux.md#network`
			`[integer-over-hex]: https://github.com/opencontainers/specs/pull/267#discussion_r48360013`
			`[keep-prefix]: https://github.com/opencontainers/specs/pull/159#issuecomment-138728337`
			`[optional-pointer]: https://github.com/opencontainers/specs/pull/233#discussion_r47829711`