As a introductory programming instructor one of the biggest things I fight with students about is documentation, and especially variable names.  Variable names are particularly difficult since beginning programmers seem to display an incapacity for choosing descriptive and helpful names.  At times it feels like a battle to get them to see that well-chosen variables can be an excellent way to make their code more readable.

Along these lines it turns out I made a choice on the current assignment that was both awful and wonderful.  The assignment has them writing three recursive functions, and the first two of them have a parameter that I chose to name depth.  Unfortunately the depth parameter for the first function represents the maximum depth of recursion for the function and the depth parameter for the second function represents the depth of indentation for printing.  Choosing the word depth for both is highly confusing and a mistake, and many students were using the depth parameter for the second function incorrectly despite my clear description of the purpose of it in the assignment.

It was an absolute delight for me to send out an e-mail pointing out my mistake and suggesting that this was precisely why they needed to choose good variable names themselves.  But it was even more enjoyable to bring it up during class yesterday after someone in each section (completely independently) had made a bad choice for a variable name.  For once they could very clearly understand how choosing a bad variable name leads to confusion.  In one section it also led to a discussion of the horrors of trying to modify someone’s code who had made bad choices for variables and failed to write documentation, something any professional programmer has experienced first hand.  The mistake on that assignment is the best teachable moment I’ve had all year.