Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Come up with and then apply a more consistent naming convention #173

Open
ivmarkov opened this issue May 25, 2024 · 0 comments
Open

Come up with and then apply a more consistent naming convention #173

ivmarkov opened this issue May 25, 2024 · 0 comments

Comments

@ivmarkov
Copy link
Contributor

ivmarkov commented May 25, 2024

Where I think our current naming convention (primarily for types and module names, but perhaps not only) is inconsistent:

  • Sometimes we abbreviate, sometimes we don't. Not the end of the world, if it wasn't the case that some types and modules contain abbreviated words and very long un-abbreviated words. Examples:
    • module sdm (System Data Model): ok, but then we have un-abbreviated system_model and interaction_model
    • ethernet_nw_diagnostics: why abbreviate network to nw when diagnostics and ethernet are not abbreviated
    • nw_commissioning - ditto
  • Sometimes - maybe - we abbreviate a bit too much:
    • EndptId - we have saved only 2 characters compared to - say - EndpointId, and the word endpoint is not abbreviated anywhere else, nor is ClusterId abbreviated which is only 1 char shorter
    • We are not always consistent: ethernet_nw_diagnostics, but then EthNwDiagCluster. If we abbreviate the cluster name, perhaps we should abbreviate the module name as well, i.e. eth_nw_diag?

The list can continue, and probably the first step would be to identify a set of names that need to be refactor-renamed, as well as a justification why.

Ideally, we should be consistent in our abbreviations, even if we won't overdo it by building a glossary (but consulting the internet and then using common abbreviations, like here and here should be mandatory).

  • I.e. ideally "ethernet" should be abbreviated everywhere to "eth" or not abbreviated everywhere. There should be few if any exceptions to this rule.
  • I.e. ideally we should use the same abbreviation for a concrete term (if abbreviated at all) everywhere

I don't think we need to waterfallish-ly come up with a long list of identifiers for renaming and only then open a giant PR for that. Yet we should probably follow at least these two rules:

  • A rename PR should only be a rename PR and nothing else. No change in the behavior of the code
  • Until something is renamed (abbreviated or not), we should use the most popular name for the thing in the code, regardless whether we like it, so that the code looks mostly consistent
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant