[Chicago-talk] code review discussion

[brian d foy]

> 3) That having been said, the speaker did a very poor job explaining
> why he was using such a huge hammer for such a simple problem. He had
> a good reason, of course, but he spent so little time motivating the
> solution

I think that in any real situation, most of the people looking at the
code would already know a lot of that stuff. The combination of the
problem domain (dealing with CME files), the particular architecture,
and the implementation, combined to make things tougher than they
needed to be.

We should have controlled that more. I made the point in my talk that
code reviews should pick something to review, but we didn't really
state what we would review in the last one. We could have done that
much better.

However, a lot of this also suffers from a complete lack of
documentation in all the samples after mine. Writing documentation is
one of the ways that you figure out how to explain what you are doing
and why you are doing it. If you don't go through that exercise
beforehand, you'll probably won't be able to organize the ideas in
your head to explain them to someone else.

Also, code reviews shouldn't be code demonstrations with the code
author explaining the source to the reviewers, and we let that slip a
bit. You don't get to see how understandable the code is if you have
the side channel of the author explaining it as you go along.

Thanks for the feedback, :)


-- 
brian d foy <brian.d.foy at gmail.com>
http://www.pair.com/~comdog/