Style Guide¶

The goal of the style guide is to describe in detail naming conventions for developing HELICS. Style conventions are encapsulated in the .clang_format files in the project.

We have an EditorConfig file that has basic formatting rules code editors and IDEs can use. See https://editorconfig.org/ for how to setup support in your preferred editor or IDE.

Naming Conventions¶

All functions should be camelCase

PublicationID registerGlobalPublication (const std::string &name, const std::string &type, const std::string &units = "");

EXCEPTION: when the functionality matches a function defined in the standard library e.g. to_string()

All classes should be PascalCase

class ValueFederate : public virtual Federate
{
public:
    ValueFederate (const FederateInfo &fi);
}

class methods should be camelCase

Publication &registerGlobalPublication (const std::string &name, const std::string &type, const std::string &units = "");

Exceptions: functions that match standard library functions e.g. to_string()

Enumeration names should be PascalCase. Enumeration values should be CAPITAL_SNAKE_CASE

/* Type definitions */
typedef enum {
    HELICS_OK,
    HELICS_DISCARD,
    HELICS_WARNING,
    HELICS_ERROR,
} HelicsStatus;

Constants and macros should CAPITAL_SNAKE_CASE
Variable names: local variable names should be camelCase member variable names should be mPascalCase static const members should be CAPITAL_SNAKE_CASE function input names should be camelCase index variables can be camelCase or ii,jj,kk,mm, nn or similar if appropriate global variables should gPascalCase
All C++ functions and types should be contained in the helics namespace with subnamespaces used as appropriate
```
namespace helics
{
    ...
} // namespace helics
```

C interface functions should begin with helicsXXXX

HelicsBool helicsBrokerIsConnected (HelicsBroker broker);

C interface function should be of the format helics{Class}{Action} or helics{Action} if no class is appropriate
```
HelicsBool helicsBrokerIsConnected (HelicsBroker broker);

const char *helicsGetVersion ();
```
All cmake commands (those defined in cmake itself) should be lower case
```
if as opposed to IF
install vs INSTALL
```

Public interface functions should be documented consistent with Doxygen style comments non public ones should be documented as well with doxygen but we are a ways from that goal

/** get an identifier for the core
    @param core the core to query
    @return a string with the identifier of the core
*/
HELICS_EXPORT const char *helicsCoreGetIdentifier (HelicsCore core);

File names should match class names if possible
All user-facing options (e.g. log_level) should be expressed to the user as a single word or phrase using nocase, camelCase, and snake_case. Do not use more than one synonymous term for the same option; that is, do not define a single option that is expressed to the user as both best_ice_cream_flavor and most_popular_ice_cream_flavor.

Exception: when defining the command line options, the command-line parser already handles underscores and casing so there is no need to define all three cases for that parser.