14: Explaining Comments

You know that moment when you're reading code and you say...

Oh, so that's what's going on!

That's a valuable moment. Record it! Write down only what wasn't obvious from the code.

Put yourself in the shoes of the future reader (or yourself 15 mins ago). What would you have liked to have known? Write to someone specific even if they aren't much like you.

Are you the only biologist on the team? Then you'd better explain any biology context in the code, even things that seem obvious to you. Think from the perspective of someone else. Try to preemptively address likely questions.

A great time to do this is upon finding a defect.

Reminder: Comments should not take the place of well factored, expressive code.