Skip to content

Commit

Permalink
style: Document recent Go-pointer exceptions
Browse files Browse the repository at this point in the history
The general rule seems to be:

  If Go's default value has the same semantics we'd use for an unset
  value, don't bother with a pointer.

I'm not sure how well that squares with [1]:

  We want a consistent way to identify unset settings.

But if the falsy values count as "unset", maybe the "null is a
consistent identifier for unset" approach was never really viable.

Qiang points out that pointers are required to opt-out of boolean
settings where both true and false would require action [2], so I've
worded the exception to only apply when the Go default for the type is
expicitly a no-op in the spec.

I'm also not sure if the new style extends to integers where zero has
the same semantics as unset values.  It sounds like Michael was ok
with no pointers for those values [3], but OOMScoreAdj (where zero
clearly means "do nothing") got a pointer in opencontainers#233 [4].  More clarity
on the threshold would be nice; in this commit I've laid out the logic
and not explicitly listed the types it applies to.

[1]: opencontainers#233 (comment)
[2]: https://github.com/opencontainers/specs/pull/317/files#r50932706
[3]: opencontainers#233 (comment)
[4]: https://github.com/opencontainers/specs/pull/233/files#diff-34c30be66233f08b447fb608ea0e66bbR206

Signed-off-by: W. Trevor King <[email protected]>
  • Loading branch information
wking authored and Ma Shimiao committed Aug 18, 2016
1 parent 3bbe47e commit b2351d9
Showing 1 changed file with 5 additions and 0 deletions.
5 changes: 5 additions & 0 deletions style.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,14 @@ The redundancy reduction from removing the namespacing prefix is not useful enou
## Optional settings should have pointer Go types

So we have a consistent way to identify unset values ([source][optional-pointer]).
The exceptions are entries where the Go default for the type is a no-op in the spec, in which case `omitempty` is sufficient and no pointer is needed (sources [here][no-pointer-for-slices], [here][no-pointer-for-boolean], and [here][pointer-when-updates-require-changes]).


[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
[no-pointer-for-boolean]: https://github.com/opencontainers/specs/pull/290#discussion_r50296396
[no-pointer-for-slices]: https://github.com/opencontainers/specs/pull/316/files#r50782982
[optional-pointer]: https://github.com/opencontainers/specs/pull/233#discussion_r47829711
[pointer-when-updates-require-changes]: https://github.com/opencontainers/specs/pull/317/files#r50932706

0 comments on commit b2351d9

Please sign in to comment.