Today I'll be sermonizing on Java, my
dear readers. I have observed since I began learning Java in my third
semester of Computer Science Engineering undergraduate course that
comments are a vital part of a program or rather the source code.
But, never were we taught about good commenting standards and
commenting conventions. Also, our exposure to the Javadocs was
minimal. Our only interaction with the Javadoc was when the IDE
(Netbeans or Eclipse or any other) would produce a small popup window
with a summary about the keyword over which our mouse pointer was
hovering.
It fills me with sadness that such
vital skills of reading, navigating, understanding and producing
Javadocs was never taught or even appreciated. Like some unspoken
truth, we all kept mum and so did our teachers, that we’ll
eventually learn it “on the job” or “later in life”. I
seriously doubt about the many Indian, so called, software
professionals knowledge on how to comment code correctly and
generate usable Javadocs or read other programmer’s Javadocs. Any
Java programmer worth his salt must have this essential skill of
playing around with the Javadocs.
There are various commenting styles in
the art of programming each style has a certain aim in mind. Some of
the commenting styles can be roughly categorized as:
- Explanatory/Verbose Commenting – Used by experts, teachers and trainers to explain in detail what each line of the code does. It is generally regarded as “How?” themed commenting. It is also used when a complicated piece of algorithm is implemented which cannot be understood without certain explanatory aid. This style is generally picked up by students from their teachers, but, is not good for day to day professional use. Most of what any programmer will code in life will be simple and easy to understand without any comments. The best code is self-explanatory without necessitating a single line of code.
- Reasoning/Terse Commenting – Used by professionals in day to day coding, it involves adding comments only when a certain part of the code is not self-explanatory and departs from the ordinary trend of coding. For example the forking of a certain thread to handle background tasks etc. It is generally regarded as “Why?” themed commenting. In other words it is a minimalist approach to commenting. You comment only when it is most required.
- Documentation Commenting – Used to generate documents or guide other programmers using your source-code either as an API or a Legacy code. It may detail hardware and software dependencies, performance issues, code vulnerability (Yeah, you’ll find in some legacy codes useless warning comments such as, “//DON’T TOUCH THIS CODE! EVERYTHING WILL BREAK. TALK TO BOB BEFORE EDITING THIS CLASS”, where Bob is someone who has left the company 15 years ago. Good luck with that, mate.) This commenting style is best seen in Open Source APIs, where you can seek help from Open Source communities which may take a longer time to resolve your issues and even third party licenced APIs, though they provide a paid support service to resolve your issues in the least time possible.
Note: No adherence to a single style
is requisite. Often, a mix of all styles will be required to deliver
a useable and malleable source-code.
Javadocs, ahoy!!
Javadoc is a documentation
generator from Oracle
Corporation for generating API
documentation in HTML
format from Java
source code. (Yes. This line is ripped off from Wikipedia. Now,
please, don’t label me as a plagiarist.)
Javadoc handles only a specific format
of commenting within the Java source codes. It can be either
generated by using the pre-bundled javadoc tool with the JDK or
invoking it via any Java compatible IDE (I’ll be sticking with
Eclipse in this blog. Go to hell, Netbeans! *Just joking! I know how
many of you still depend on it and I can empathize with you.*).
I’ve attached the source-code of a
simple java program (which I did not care to test run even once.
Don’t bother compiling and running it. Our focus should be on
commenting for Javadoc.) with screen shots of generating and using
the related Javadocs of this project. [The screen-shots are available
here only, as my paid internet data usage quota has expired and I am
currently blogging at the speed of 3~4 Kbps. I promise to update the
bundled project with screen shots after I get my internet connection
recharged which is looking doubtful considering I have already paid
for the recharge and the confirmation SMS or transaction SMS has not
yet been received since today morning 8 AM or so.]
Now, let’s see. Step 1:
Select the Element you want to comment
on. Like in the above screen grab, I’ve selected method Circle from
class FigureStore.
Step 2:
Select the Generate Element Comment
option from the drop down menu of Source button from the main menu.
Step 3:
Eclipse auto-generates the comments
depending on the selected element. As here the selected method Circle
has two parameters, the Radius as X and the Diameter as Y.
Step 4:
Now, edit the element comment as
required. Try adding details as briefly as possible.
Step 5:
After you’ve added all the element
comments you need to generate the Javadoc. For generating the Javadoc
for your project, select it in the package explorer and the choose
Generate Javadoc from the Project option in the main menu.
Step 6:
Now, you’ll see a dialog as shown in
the above image. Make sure your project is selected as well as all of
its components. The Javadoc tool is selected via the Configure
button. The Javadoc tool is present in the “bin” directory of the
JDK. Also, set the path of your doclet to a new “doc” directory
of your project.
Step 7:
You can add a specific document title
to your doclet and you may add any referenced/dependent jars and
packages which mainly comprise of the JDK libraries. Then select
Finish. (Yes, I don’t go any further with that alluring “Next”
button.)
Step 8:
Now, sit back and relax for a few
moments while the Javadoc is being generated. The time take for
Javadoc generation is dependent on the number of Elemental Comments,
program size, structure etc. Your Console should show something like
this:
Alternate Method:
Here’s an alternate method to
generate Javadocs. Right click on your project in the Package
Explorer. Select “Export” from the drop down menu and a dialog
will appear as shown below.
Select Javadoc from the Java directory
and Bam! It’s done (It’ll take you to the Javadoc Generaton
Dialog).
What to expect from Javadocs?
You’ll see a new directory under your
Project in your Package Explorer called “doc”. Exanded it’ll
look like this;
The “index” html file is the start
or main page of your Javadoc. Double click on it to open it inside
Eclipse. A sample Javadoc is shown below;
Also, now you’ll be able to invoke
small popup help windows for your project/package which can be used
in other projects as well if the Javadoc is imported in there Project
directories.
IMPORTANT END NOTE:
A good habit is to keep on making
Element Comments while programming in order to keep the burden of
commenting low. Once the size of the source code gets out of hand
commenting becomes difficult and you’ll not be able to leverage the
Javadoc prompts for other parts of your source-code.
“Also, one must always try to keep
deprecated (i.e discontinued) methods in future iterations and newer
versions of the program/package in order to maintain backward
compatibility.”
Sample Documents and Source Codes::
No comments:
Post a Comment