Dear Sir or Madam will you read my JavaDoc?
It took me 'while to write, agonise will you take a look?
It's based on a spec by a person very dear
And I need a job and I wanna be a JavaDoc writer,
JavaDoc writer...
Do you write JavaDocs? I'm not sure how productive this would be to you, but I personally find writing JavaDoc for trivial methods, especially those requires a little thinking, ensures that I fully understood what I need to do before I start my Pee Wee's big adventure.
Once upon a time, on one lazy Friday afternoon, I restricted myself with TDD approach, that is write test code before implementation. It occurred to me that my input field will be populated by a name thus, I need to break them down into first name and last name. Easy-peasy, invoke split method from String class and pass space character as delimeter! The first element of returned String array will always represent the first name and second element will always represent the last name.
Before I started the name-parser method implementation, I wrote a small documentation right on top instead. Since I never had a poetic license in my entire life, let alone enrolled myself in three semesters of English-lit during my Uni days, my JavaDoc documentation was, is and will never be written as technical, as formal as I want it to be. I always end up with mediocre technical English documentation. I know I'm useless.
"Oh Uncle Bob, where art thou?"
One thing struck me as I happily started typing my doco - clackity-clack, what happens when someone calls himself "Donkey Kong Jr."? Clackity-clack.
(For argument's sake, let's put the spec aside for now.)
Surely, I can assume his first name is "Donkey" and last name is "Kong Jr." What about "King Henry VIII" and "Don Quixote de la Mancha"?
Hmmm, doesn't sound right, does it...?
I found myself dumbstruck at that particular instance, not to the problem nor to the solution, but to myself - a sudden self-pity, self-realisation of how naive and simple-minded I was.
So, do you want to be a JavaDoc writer?
Clackity-clack.
