Coding guidelines

Exceptions

When throwing exceptions please provide some information about the context, preferably print some parameter values to the what string using std::stringstream. When throwing exceptions from within the library, make sure to throw the correct one:

1. If some operation is peformed only with C API directly, upon returned error throw nested with the extracted HDF5 error stack, e.g.: error::Singleton::instance().throw_with_stack("Context for H5 call");
2. If any called function can throw, have a catch clause and then rethrow with nested, e.g.: std::throw_with_nested(std::runtime_error("Context for calling other functions"));
3. If neither of these is true, i.e. first instance of possible error and without HDF API access, then throw a simple exception, e.g.: throw std::runtime_error("Some message of what happened");

Code documentation

As per Strunck & White, and many other sources of good advice on style, things should be concise. For doxy, I would suggest the following:

Phrases to avoid:

• "a function for ..." when describing a function. We can already see that it is a function.
• "a reference to ..." when describing a parameter. It probably has an & in there, so we know it's a reference.
• "for obvious reasons" or anything else with "obvious" for that matter. If something is truly obvious, there is no need to mention it at all. If something is less than obvious, claiming that it is will likely just infuriate the reader.

Things that are ok:

• passive voice is absolutely fine to use. If it sounds good, use it.