Contributing guidelines

When contributing to Hexed, please adhere to these guidelines. Some are standard practice in software development, which I feel the need to specify since people contributing to Hexed may not be software engineers by training. Others are meant to standardize what is otherwise a matter of personal preference.

General procedures

Please do not commit or push to the main branch. The standard workflow should be the following:

1. Create a new branch.
2. Implement changes.
3. Open pull request.

After reviewing the pull request, the maintainer will merge it and delete the branch. You are encouraged to create as many new branches as you like, for any reason, even if they are just experiments you don't intend to merge. However, if you are completely done with a branch, please delete it. You are also encouraged to push frequently (at least once per work day)—productivity is maximized when everyone can see the latest version of everything. Finally, development should be test-driven as much as possible, granted the inherent difficulty of testing a computational physics solver.

Pull requests

A pull request will not be merged until it meets the following requirements:

• No merge conflicts.
• Must compile and run both in Release and in Debug mode with sanitizers.
• No unit test failures or sanitizer errors.
• No compiler warnings.

Code style

Please adhere to the following style conventions whenever possible.

File formatting

• File names must not contain whitespace or other characters that have meaning in shell commands.
• Prefer underscores (_) to hyphens (-) or camel case as word separators in file names.
• Source files must not contain the tab character. C++ code should be indented with 2 spaces and Python code should be indented with 4 spaces.
• There should be no trailing spaces at the ends of lines.
• Use blank lines sparingly.

Names

(of variables, functions, namespaces, classes, macros, etc. Anything in the code.)

• Should contain words, abbreviations, and/or numbers separated by underscores (not camelCase, and not multiplewordswithoutspaces).
• Names of classes should begin with a capital letter. Otherwise, all letters should be lowercase.
• A name should be a description of the variable it refers to. It should not reference mathematical symbols or the sound of words. For example, resist the temptation to use x to refer to horizontal position. Acceptable alternatives might be coord0, or position.
• Maintain conventions in Notation and conventions.
• When practical, avoid overly long names. Abbreviations are encouraged, especially in a local scope where there are fewer opportunities to confuse similar names.

Some examples of names I do not approve of:

• eye to refer to the identity matrix. References the pronunciation of the mathematical symbol, two levels removed from any descriptive meaning. I prefer the name identity.
• str2num to mean "string to number". Just call it str_to_num. Distinguishing between "2" and "to" is worth 3 extra characters.
• I have seen names longer than this sentence. Save some for the comments.

Exceptions

If the code encounters a fatal problem, it should throw an exception (using the constructs of whatever language it is currently in) with a helpful error message. The message should identify what exactly was found to be wrong so that someone capable of understanding the problem has a clue where to start trying to figure out why. In the interest of performance, some functions in the C++ API may produce segmentation faults, memory leaks, or undefined behavior upon incorrect usage. However, the executable should catch incorrect usage and throw a useful exception. If an end user makes a mistake and obtains a segfault instead of an exception, I consider that a bug. Some common things I would like to avoid in this code are:

• Don't just say something vague like "something went wrong" "the operation could not be completed" or give a numeric error code that the user then has to look up to get any information. I'm thinking of the error messages commonly encountered in a certain operating system whose name ironically evokes transparency. Error messages should be as specific as possible.
• Don't presume to guess exactly why the problem occurred or give verbose suggestions about how to fix it. Exceptions generally occur because you failed to anticipate what actually happened, so your speculations are probably a waste of space at best and actively misleading at worst. Just say what the exact, concrete problem was. For example, if the code encounters a nonphysical state, don't say something like "The solver is unstable. Try reducing `max_safety` and verifying the boundary conditions are correct." Instead, say something like "nonpositive density encountered in flux computation".

Hexed provides the HEXED_ASSERT macro to facilitate generating exceptions with detailed information about where the error occurred in the code.

See also

Error Types

Miscellaneous

• Avoid using namespace. The code is clearer when namespaces are referenced explicitly.
• Everything in the library must be wrapped in the namespace hexed to avoid creating naming conflicts for library users.
  • Macros, which do not respect namespaces, should be either prefixed with HEXED_ or #undef'd after they are no longer needed.
• Code should conform to the ISO C++ standard. For example, don't use variable-length arrays or the constexpr form of std::pow, which are non-conforming features of GCC (for constexpr math functions, see hexed::math).
• The default integral type should be int. For example, don't use unsigned for loop indices and array sizes unless there is a specific reason to.