Documentation: Docs Docs Docs

One of the major reason I love programming in Java, is the excellent quality of the documentation. I can look up any class, method, field, enum, annotation, or even an entire package and get loads of great documentation on the subject. It doesn’t just tell me what it does, it also tells me valid inputs, outputs, what exceptions can be thrown, and often even the process the code goes through.

I’ve heard many people tell me: just look at the code, it’s really self-explanatory. I used to work as a trouble-shooter, so climbing into code quickly was basically my job. The fact of the matter, there’s no substitute for good documentation, none! On a side note: my IDE’s auto-completion window comes up with the field or methods documentation. Sure the code is a CTRL-Click away, but that’s an extra step, and another trawl through other code that I really don’t need.

Personally I love writing documentation explaining how my code works, where it has flaws and where it’s really cool. One annotation I wrote yesterday is a marker annotation (ie: it’s got no attributes), I wrote over 30 lines of documentation for it. It probably sounds like overkill to most people, but trust me on this, without it, people would have to spend a whole lot of extra time figuring out what my code does.

The message here is: don’t forget to document your code!

Advertisements

One Response to “Documentation: Docs Docs Docs”

  1. Lijin Says:

    Yea sure merrak. Documentation is an important thing and sign of a good programmer. 🙂


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: