notes from yesterday's code review;
minor clarification;