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 &fedInfo); }
class methods should be
camelCase
Publication ®isterGlobalPublication (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 bemPascalCase
static const members should beCAPITAL_SNAKE_CASE
function input names should becamelCase
index variables can becamelCase
orii,jj,kk,mm, nn
or similar if appropriate global variables shouldgPascalCase
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 usingnocase
,camelCase
, andsnake_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 bothbest_ice_cream_flavor
andmost_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.