search

GMLC-TDC / HELICS

Hierarchical Engine for Large-scale Infrastructure Co-Simulation (HELICS)
https://docs.helics.org/en/latest/
BSD 3-Clause "New" or "Revised" License
127 stars 41 forks source link

C-API feature request: Naming conventions #1311

Open kdheepak opened 4 years ago

kdheepak commented 4 years ago

Use a consistent naming convention for the C API, that allows users to identify various kinds of objects just by reading the code.

Proposal

Use camelCase for functions:

helicsGetVersion
helicsFederateInfoSetCoreName
helicsCreateBroker
helicsErrorInitialize
...

Use PascalCase for types:

HelicsFederate
HelicsQuery
HelicsInput
...

Use SNAKE_CASE for enumerations:

HELICS_HANDLE_OPTION_STRICT_TYPE_CHECKING
HELICS_FLAG_TERMINATE_ON_ERROR
HELICS_PROPERTY_TIME_DELTA
...

Currently, camelCase is used for all functions, but snake_case is used for types for and enumerations, which makes it somewhat confusing when reading a function like this:

helics_federate_info = helicsCreateFederateInfo()
h.helicsFederateInfoSetFlagOption(helics_federate_info, h.helics_flag_terminate_on_error, True)

The above is actual python code in the wild right now. In Python, the type name and the variable name (helics_federate_info) are the exact same string. This just decreases readability.

Also, it is hard to do a case sensitive search on a code base and find where enumerations are used.

In Julia, since the code is not generated from swig, this is what it looks like:

helics_federate_info = helicsCreateFederateInfo()
h.helicsFederateInfoSetFlagOption(helics_federate_info::FederateInfo, h.HELICS_FLAG_TERMINATE_ON_ERROR, true)

Uses a case sensitive regex, it is very easy to identify types, enum, function names and variables.

phlptp commented 4 years ago

We should set up a meeting in the next couple weeks to discuss formalizing some of these things. It would be really nice if we could get them added into rules like clang-tidy, so they can be checked and enforced. I think in about a month we will in a place to start making some of these kinds of changes for HELICS 3.0

trevorhardy commented 4 years ago

Given the naming conventions meeting a few weeks ago, I'm assuming this is wrapped up. @phlptp or @kdheepak, can you post the results of that meeting and close out the ticket? I'm assuming/hoping we wrote down the guidelines somewhere and this won't be a big lift.