Typo/Inconistent naming in Pause helper functions

[twitu]

A method and macro attribute standard for the pause utility is named paus which looks inconsistent compared to other methods which are named with full pause.

https://github.com/NEARFoundation/near-contract-tools/blob/aad160bb15455eff3bb3b733d0e9da46bb01ceae/macros/src/pause.rs#L46-L49

https://github.com/NEARFoundation/near-contract-tools/blob/aad160bb15455eff3bb3b733d0e9da46bb01ceae/src/pause.rs#L25-L32

[encody]

The idea here is that different patterns use different prefixes (like own for owner). I kind of just made up paus on the spot for the pause-related functions & events. Open to discussion.

https://github.com/NEARFoundation/near-contract-tools/blob/aad160bb15455eff3bb3b733d0e9da46bb01ceae/src/owner.rs#L245-L265

[ryancwalsh]

I personally prefer verbosity. Abbreviations can be confusing and riskier (more subject to misinterpretation), especially across languages and cultures.

I like how Petar added this rule to our standard Eslint config that we're now using: https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/prevent-abbreviations.md

Do these function names even need prefixes? If yes, I wonder if it would make sense for the prefixes to be owner_, pause_, etc (or maybe something even longer, such as owner_external_ or whatever could refer to a name of that section of code)?

[encody]

This is intended to be consistent with the pattern adopted by existing NEPs. For example:

• nft_ for NEP-171
• ft_ for NEP-141
• mt_ for NEP-245

Although I also prefer verbosity, I think convention & consistency with the ecosystem is worth mentioning.

Also, at least to me, it is not obvious that owner_ is a prefix (i.e. namespace), as opposed to simply a word at the beginning of a longer method name. That, of course, implies that own_ is also not a good prefix for the owner pattern, which is a point I'm willing to concede.

That is to say, the prefix is intended to be an identifier, and obvious as an identifier. I think that it is not intended to carry meaning beyond identification, although the prefixes thus far have been derived from the human-readable name of the standard / namespace they represent.

[encody]

This is also relevant if we intend to propose the components that expose external functions as NEPs.

[ryancwalsh]

Yes, convention & consistency with the ecosystem is definitely worth considering.

Also, NEAR is new enough (and NCT may become important enough) that maybe this will help define convention going forward.

I don't have strong opinions here.

I'm curious what prefixes you're currently leaning towards @encody and also what @nearken , @sandoche , @twitu, and @RobertNear think too.

[sandoche]

I agree with @encody, i'll avoid prefixes everywhere, except for standards such as ft, nft, mt

[encody]

If I were to propose a naming standard in a vacuum, it would probably be something like:

The names of the functions of a standardized interface shall be composed of:

1. The characters nep.
2. The standard's number, e.g. 141 for NEP-141, 171 for NEP-171.
3. Two underscores __.
4. The rest of the name of the function:
   1. Must be composed of words joined (separated by) single underscores _.
   2. A "word" is a sequence of lowercase alphanumeric characters.

Regular expression for general form: /nep\d+__[a-z0-9]+(_[a-z0-9]+)*/
Regular expression for NEP-9999: /nep9999__[a-z0-9]+(_[a-z0-9]+)*/

In the case of methods unique to an individual contract (not a standard), prefixes as described above should not be used.

Examples

Valid names for methods exposed as part of NEP-9999:

1. nep9999__hello
2. nep9999__a_b_c
3. nep9999__hello
4. nep9999__123
5. nep9999__12_34_56

Invalid names for methods exposed as part of NEP-9999:

1. nep0__hello
2. nep__4
3. nep9999__
4. nep9999___
5. nep9999____
6. nep9999__12_34_56_
7. hello
8. NEP9999__hello
9. nep9999_hello

[twitu]

A couple of points to add to uniform naming convention, since I've been looking at more code.

Traits to expose external functions have the same keyword as prefix and suffix. Since prefix is needed to avoid namespace collision the suffix can be removed. It'll also result in shorter names without any loss of information. Along with the proposal for fully named prefixes the OwnerExternal would look something like this.

#[ext_contract(ext_owner)]
pub trait OwnerExternal {
    /// Returns the account ID of the current owner
    fn owner_get(&self) -> Option<AccountId>;

    /// Returns the account ID that the current owner has proposed take over ownership
    fn owner_get_proposed(&self) -> Option<AccountId>;
    ...
}

Currently the functions are own_get_owner and own_get_proposed_owner.

[twitu]

@encody on your suggestion for naming convention. The separator could be a single underscore _, which would keep it consistent with snake case function naming convention. Double underscore would also give linting warnings rust-lang/rust#19475.

If there's no specific reason for double underscores we could go with single. The other parts look good 👍.

[encody]

The reason for the two underscores is to make it very clear that the prefix is a prefix. If there is some other, better character combination (that wouldn't then be easy to confuse with a non-standard method name), please let me know!

[twitu]

All the functions being exposed externally will be grouped together in the same trait. It will be visually clear that the same keyword is the prefix, a separate character for distinction may not be necessary. But I'm not opposed to it, if there's something that fits the function naming convention.

[encody]

Once the contract is compiled to WASM, the types (traits, etc.) are all erased, so if you query the WASM, only the exposed function names remain. Transactions calling the contract also don't have to reference (or even know about the existence of) a trait, so none of that information is present in a block explorer, for example.