Style Guide

Any time more than a single author is involved in a project, differences in preference can diminish the code's readability. Here is the place to read up on all stylistic choices that we agree upon.

Function and Variable Names

In order to make functions and variables immediately distinguishable, function names are written in camelCase while variable names are written in snake_case.

double addNumbers(double first_number, double second_number){
  return (first_number + second_number);
}

Private members generally begin with an underscore (_member) while static members should be marked as follows: s_member.

class MyClass {
  ...
  public:
    double length;
  private:
    int _size
    inline static std::string s_word = "hello";
};

There is an important exception to this general rule. In order to be stylistically compatible with the wxWidgets library, some methods and members within the MainFrame class (derived from wxFrame) use a different convention. Event functions such as OnBrowse() use CamelCase with a leading capital to mirror inherited functions such as OnInit(). Members use camelCase with a leading lowercase letter. However, functions that are used by the Controller to communicate with the GUI generally follow the style described above.

Indents

Two-space indentation is used. Make sure you are not using tabs.

Comments

Some files can become large and difficult to overview, but it may not be sensible to split them into multiple files. Such is often the case for .cpp files containing many function definitions. Here, sections may be defined to grant a quick overview and simplify finding specific function definitions. The sections titles are written in uppercase, preceded and follow by a double slash. The line above and below the section title contains slashes to match the length of the title line.

/////////////
// SECTION //
/////////////

Comments may be made to indicate features or code blocks that are planned for future implementation. Such comments are marked by a capital "TODO" followed by a colon and a summary of planned actions.

// TODO: Implement xyz soon.

Commit messages

Much of this section is based on this article written by Bolaji Ayodeji.

Commit messages consist of a summary line and - if necessary - a body that contains further explanation. Summary line and body must be separated by an empty line, in order to allow processing by external programs. When committing via the console, git commit will open the default editor and allow writing a commit message. Alternatively, git commit -m "Summary Line" or git commit -m "Summary Line" -m "Body" can be used.

Summary Line

• Contains a short and precise summary of the changes
• No longer than 50 characters, unless clarity can be greatly improved
• Written in the imperative, i.e., Fix issue rather than Fixed issue or Fixes issue, in order to keep commit messages consistent with automatically generated commit messages, for instance Merge pull request...
• Always begins with a verb, typically but not exclusively "fix", "add", "remove", "change"

Body

• Contains information on the changes
• Wraps after about 72 characters
• If a commit resolves a specific issue, the issue can be closed by adding a line to read: Resolved: #(Issue Number)