# vs _# and capitalization

[cueckoo]

Originally opened by @extemporalgenome in cuelang/cue#686

Reading through the tutorial and the spec, I see both # and _# offered as possible prefixes for definitions but no definitive guidance on when to use one as opposed to the other. When should we use _# rather than just #.

Furthermore, it appears that definitions and aliases can all be spelled starting with either uppercase or lowercase letters. Under which circumstances should one letter-casing be preferred over another?

I'm happy to submit a docs PR with whatever I learn here.

[cueckoo]

Original reply by @mpvl in cuelang/cue#686 (comment)

This is a relatively new thing and the documentation needs to be updates. For details see https://cuelang.org/docs/references/spec/#definitions-and-hidden-fields

But in short, exported definitions (those starting with #) are visible outside your package, whereas hidden ones are not. If you don't intend to share a package, then it doesn't matter much.

There is one case where this is important though. Consider

import "acme.com/foo"

a: foo.#Def & {
    #foo: {...}
   a: #foo
   b: #foo
}

Adding a definition to a struct is currently allowed in CUE, even if foo.#Def doesn't define it. This will be disallowed in v0.4.0. See #543 for more details and discussion. The solution then is to write:

import "acme.com/foo"

a: foo.#Def & {
    _#foo: {...}
   a: _#foo
   b: _#foo
}

Hidden fields, including definitions, always live in a different namespace per package (much like Go unexpected fields) and thus are safe to add.

[cueckoo]

Original reply by @extemporalgenome in cuelang/cue#686 (comment)

I see, thanks! Couldn't the v0.4.0 solution be to write:

import "acme.com/foo"

a: foo.#Def & {
   _foo: {...}
   a: _foo
   b: _foo
}

If this is effectively equivalent, since hidden non-definition fields are excluded from output, then there might not be any reason to allow the specification of even hidden definitions within a struct.

[cueckoo]

Original reply by @mpvl in cuelang/cue#686 (comment)

It depends on whether you want _foo to be "closed" or not. So it may still be necessary to use a hidden definition there.

[cueckoo]

Original reply by @mpvl in cuelang/cue#686 (comment)

Also, hidden definitions have the same properties as regular hidden fields in that their namespace is local to a package. So there would also be no benefit to disallowing them here.

[cueckoo]

Original reply by @mpvl in cuelang/cue#686 (comment)

As for casing, the original CUE spec used casing for determine whether to export something or not, similar to Go.

However, although this works well with Go, it doesn't work well for CUE as it may be used in conjunction with data with arbitrary casing. The convention is to use camel case for JSON, but in reality it is all over the place. So we introduced the use of # instead. Note that the # is part of the identifier, so you get a similar level of clarity and a similar feel as the casing approach in Go. It just takes some getting used to.

As for a recommendation, normally I would say using # + upper case, but it really depends in which context you use CUE.