Improve codebase clarity based on feedback from PR 166

PR #166 has been the first PR for a while with a significant code contribution from someone who isn't me 😄.  So it's highlighted a few areas where improvements could be made to the codebase to make things more obvious, or more difficult to get wrong.

This ticket covers things of that nature.

TODO - form a list of individual items of feedback to work on.