I disagree with nickharr's opinion on humor just as starkly as you, but agree with the need for comments very much. And his/her point still stands regardless of how much you name and group functions. There are concerns and aspects (design/engineering decisions become implementation details that might need rationale) that can't be presented efficiently that way. (Workarounds for issues benefit a lot from links to the relevant issue trackers, and so on.)