Transfer the new code comments from the code review

Created by: mattclarke

During the code review a number of comments were added or improved. These need to be captured, so they can be added to master.