I remember vividly my first programming class in college. I remember the LAN parties and frustrated students blaming the professor for their inability to understand pointers, but most of all I remember losing points on homework for not including comments (I also lost points for including ‘return 0;’ in my main functions).
Needless to say, I became a comment machine. I needed those points… it’s not like my exam grades were going to drag up my GPA! If I didn’t lose points for trying too hard and being a jerk at that point, I should have. I recall wasting about 30 lines on a nursery rhyme in one instance, but it was all in good fun.
Fast forward some years and I’ve made the better part of a full jump from C++ to Java. Comments, as well as verbosity in naming conventions, would seem to be king. This very cool thing we know as JavaDoc has seemingly turned every programmer into a technical writer virtually overnight. Along with the usual language ineptitude that is so prevalent among the technically inclined, there does also seem to be the occasional developer with a clue about writing form (or at least how to construct a complete sentence).
Its fascinating what a relatively small investment in time can do for code. By simply writing comments, IDE’s suddenly spring to life with documentation just by hovering over method calls! In-source documentation isn’t everything though, and eventually we all must embark upon the daunting task of compiling some sort of human digestible document about our efforts.
This time its for Betaville, and thank goodness its not me taking the lead (Disclaimer: I absolutely love writing, but I’m cramming 22 hours of Betaville into a day over the past year or so; I’m running out of space). I have, however, had the opportunity to contribute a nice chunk of writing to the effort. Its an impressive document to see come together, and I felt some familiarity with the wording as I read over (and wrote additions to) it in some places. It finally hit me that much of what is written has been derived from JavaDoc already in the code base! It was exciting to think that the comments being written throughout the application over all this time finally mean something to more than three people, but the real bonus is how much time this head start has likely saved. Its a nice feeling, to say the least.
Now with a bit of a prompt, I’ve embarked on writing better database documentation for the project. This is kind of an awkward area as the database should, by nature, be fairly self-explanatory if one is already familiar with the application it is supporting. To this extent, I haven’t seen much in the way of documentation with the exception of what the WordPress team puts out. It seems acceptable, but doesn’t provide much more information than a UML-styled chart would provide. Hopefully I can improve on this a bit in my own efforts, but I suppose we’ll find out about that at a later date.
It is funny though, as I reminisce about that first semester of college I find myself very much in need to gather some people and play the PC Halo demo over LAN once more. Ah, simple times.