Presenting / explaing code and design decisions to team members

Question

I am working on a project where I will have to regularly justify and explain my code and design decisions to team members who are not directly involved in the same area of the project as I am.

How can I best explain my technical design decisions to team members in a different location? Are code walkthroughs worth the time for team members not directly involved, or would written explanations and annotated code be better? If I do decide to heavily comment my code to explain design decisions, then should I do that in a separate copy of the code?

Answer 1

IMHO, commenting your code well is probably the best way to convey this information. Big manuals or even design documents go out of date quickly as the code base evolves. Besides that, a programmer is less likely to sit down and page through a thick manual than to go and poke around in your code to figure out what's going on.

If your code is designed well enough that its structure is self-documenting, then the comments you add to explain your algorithms and such will supply the rest of the information other programmers will need to make sense of your code.

As was mentioned, its easy to extract comments for generating API docs in a lot of languages. That's another useful thing to do.

Answer 2

I like simple diagrams drawn by hand for design explanations. But you have to keep it really simple, don't overload it with full architecture diagrams and every little detail. Talking your colleagues around the diagram will make it a good discussion and if they ask questions about it the time is worth so much more than a speech of your own.

When it comes to documenting the code, I'm a huge fan of Clean Code. If you are carefully naming everything you should only drop a line of comment if there really is a design decision behind the code that made you choose an uncommon way. I generally avoid lots of documentation (like javadoc) in my code.

Here's what I do:

• keep methods simple
• 1 level of detail in your methods
• good names for variables, methods, classes

I also try to avoid the hackery stuff in my code. If you need to explain a single line in your code, because you used the fanciest and shortest way to do things, you probably drive The Next Developer crazy.

And, the big thing: Provide test cases (maybe unit tests) for your code, so other developers can run them, see what happen and actually see how your code was intended to be used. I think having test cases as a way to document your code is a really nice way for other developers to get used to your code. Same rules apply to test cases than to your code: Make it clean.