Geeks With Blogs
Joseph Hachey blog

Today, in COSC202H: Data Structures & Algorithm Design, I was finally handed back Assignment 1, which I submitted almost 2 months ago. The assignment was to implement a handful of different Hash Tables with differing insertion/collision resolution algorithms, and compare their performance (collisions & clustering) when giving the same test cases. 

In the marking scheme, I noticed 5% was deducted for not including a “Data Dictionary” with the documentation. This annoyed me as the assignment handout requested “Program and Testing Documentation”. Nowhere did it specifically mention a Data Dictionary.  I did, however, write javadoc-formatted in-line documentation for all my classes, functions, and member variables, which compiled out to a very nice HTML API that was handed in with the source code and binaries.

When I argued to the professor that my java-docs met the requirements of a Data Dictionary, he quickly scanned through my printed-out code listings and asked: “Show me where you define the variable 'probeCount'”. I said, “ the java-docs don't define local variables, but I have good naming conventions!”. He snickered and replied: “That's what all you students say: Sir, I use good naming conventions. Isn't that enough? Wait until you get into the real world and have to maintain a system consisting of tens of thousands of lines of code without a Data Dictionary before you ask if proper naming conventions is enough!”

Since when did a local variable's scope span across thousands of lines of code!?! I already defined every class's member variables. Is it really necessary to write a document that includes definitions for every single local variable in every function? I'm sure anyone who reads the code could make an inference that probeCount is used to count the number of probes! If you couldn't figure it out from the variable's name, scanning down a few lines you would notice that within a loop, probeCount is incremented every time a probe is made. Maybe that would give it away? Should I have written definitions for i, j, and k too? But I use those same three variable names for loop indexers in more than one function. Should I qualify them by function name and define each instance?

If there's one think I hate, it's make-work projects!

Posted on Tuesday, November 29, 2005 5:47 PM | Back to top

Comments on this post: Java-doc != Data Dictionary??

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © Joseph Hachey | Powered by: