This week's book giveaway is in the Agile and Other Processes forum.
We're giving away four copies of The Little Book of Impediments (e-book only) and have Tom Perry on-line!
See this thread for details.
Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Java doc question...

 
christy smile
Ranch Hand
Posts: 101
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi, All,
I am fixing up my javadocs. I have a couple questoins would like to get clarified:
(1) Do I need to provide JavaDoc for private member variables and private methods? Also, what about the protected (default)? The Data class provided by Sun did not have JavaDoc for these.
(2) This is not related to JavaDoc though. I have read somewhere that it is good programming practice to avoid using import statements with "*", does this apply to the SCJD? I noticed the source code Sun provides use imports with "*" everywhere.
Thank you!
 
christy smile
Ranch Hand
Posts: 101
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi, All,
In addition to the previous two... There is another convention that I follow normally when I write code. For member variables, they start with "m", e.g. if a member variable is "data", I will call it "mData". And for parameters passed into a method, they are prefixed by "p". e.g. a parameter called "data" would be called "pData". Should I use this convention in SCJD?
Thanks.
Christy
 
Valentin Crettaz
Gold Digger
Sheriff
Posts: 7610
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
In my opinion, you should provide a Javadoc for any members, private or not, since it is possible to generate documentation for private members with the Javadoc tool.
Importing on demand (i.e. *) is a bad programming practice. If you browse through the JDK sources, you will see that each class imports only the types it needs. You will rarely see import on demand.
As for you second question, it should suffice if you follow the Sun's Java coding conventions.
[ September 30, 2002: Message edited by: Valentin Crettaz ]
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Originally posted by Christy Smile:
(1) Do I need to provide JavaDoc for private member variables and private methods?

I agree with Valentin on this. Javadoc everything. As Valentin indicated you can document to any accessibility level, but you may also later determine that a variable or method should be protected instead of private.

Originally posted by Christy Smile:
The Data class provided by Sun did not have JavaDoc for these.

Add the javadocs yourself. The DatabaseException source had no javadoc comments at all. How will it show up in your API documentation if you don't take care of it?

(2) This is not related to JavaDoc though. I have read somewhere that it is good programming practice to avoid using import statements with "*", does this apply to the SCJD? I noticed the source code Sun provides use imports with "*" everywhere.

Valentin is right on this point too, but I don't think you will be penalized if you do this. The reason I say this is that I scored perfect on general considerations (which takes all coding conventions into account) and I used * imports extensively. Some lazy habits are hard to break
Hope this helps,
Michael Morris
 
Pete Lyons
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Definitely go through the Sun code and add/fix the javadoc. Some of it does not follow convention, particularly the @param tags.
As to imports, I can't stand explicit import, but if you decide you want to do it, there are many great tools that will take your on-demand import statements and fill in the specific classes, plus alphabetizing, etc. Do a google search for some. I have used Jalopy (specifically the Ant plugin) with some degree of success.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic