# Hints and considerations for completing PHAS0100 assignments

### Code layout/formatting

* Make sure all header (`.h`) files have an [include guard](https://www.learncpp.com/cpp-tutorial/header-guards/) to prevent accidental double declaration of variables/functions/classes (alternatively you can use`#pragma once` --- it's less typing but it is not part of standard so not guaranteed to be available for every compiler)
* Header files should only contain function/class/variable declarations (the interface) not their definitions (the implementation). Definitions should go in a corresponding source (`.cpp`) file --- this keeps interface and implementation separate, speeds up compilation and avoids double definitions of functions/classes/variables
* Choose a consistent formatting style (for example [the google C++ style guide](https://google.github.io/styleguide/cppguide.html)) and stick to it. The focus should be on readability:
* Use descriptive variable, function and class names that describe the purpose/intent of an object and would be understandable to someone reading the code for the first time;
* Be consistent with indentation. Use 2, 4, etc spaces and stick to it. Avoid tabs as these can show up differently on different editors (use automatic tooling to help you with that);
* Comments in the header files should describe what a class/function is for and how it should be used (unless it is obvious from the function name). Avoid stating the obvious or describing literally what the code does when commenting in the implementation (`.cpp`) source files. Use comments for _tricky, non-obvious, interesting, or important parts of your code_ (from [cppguide#Comments](https://google.github.io/styleguide/cppguide.html#Comments))

### Unit tests

* Each unit test TEST_CASE should at least one meaningful assertion to check a condition has been met. Avoid meaningless checks such as `REQUIRE(true)` that will always pass. To check that a class can be instantiated you can use `REQUIRE_NOTHROW` or `REQUIRE_THROWS` to check that an exception is not/is thrown as expected, for example:

TEST_CASE( "FileReader file reader instantiation" , "[FileReader]") 
{
  REQUIRE_NOTHROW(FileReader("file_that_exists.txt"));
  // should throw an exception for non-existent file
  REQUIRE_THROWS(FileReader("file_that_does_not_exist.txt"));
}

* To improve coverage of your unit tests consider whether you have fully tested the behaviour of the object or function that you are unit testing:
* Have you tested for known solutions that you can compare to?
* Have you tested a range of representative use cases, not just one specific case?
* Have you tested for failure (like invalid inputs where you expect the constructor to throw an exception) and edge cases (special cases like the square root of 0)?
* Use the `APPROX` catch2 method when comparing floating point numbers, for example:

TEST_CASE( "Average", "[MathsUtils]" ) {
  // to compare within floating point precision
  REQUIRE(GetAverage(10.0,20.0) == Approx(15.0));
  // or to compare a result to within your own defined precision
  REQUIRE(GetAverage(10.1,10.2) == Approx(10.0).epsilon(0.02));
}

### Commit messages

* Commit messages should describe the changes being made and have enough information that someone could come back and find out where a specific change was introduced
* Avoid bundling many changes into a single commit: this makes it harder to understand what has been changed in each commit and also harder to use tools such as `git bisect` to locate a change that may have introduced a bug
* Keep the first line of commit message concise (i.e. brief but with lots of info) and add more details as part of the message body if needed

### Submission

* Use `git status` to check you have committed all files required to build and run your project
* Always double check you code compiles before submitting
* Don't commit build products into your git repository i.e. don't include the `build` directory (you can `git rm -r build` it if you've already committed it)
* When zipping your submission make sure the `.git` hidden folder is included otherwise the git historgy will not be available
* To be sure that what you have submitted compiles we recommend downloading your submission and checking it compiles in a clean container