• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Ron McLeod
  • Paul Clapham
  • Devaka Cooray
  • Tim Cooke
Sheriffs:
  • Rob Spoor
  • Liutauras Vilda
  • paul wheaton
Saloon Keepers:
  • Tim Holloway
  • Tim Moores
  • Mikalai Zaikin
  • Carey Brown
  • Piet Souris
Bartenders:
  • Stephan van Hulst

Java doc question...

 
Ranch Hand
Posts: 101
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Author & Gold Digger
Posts: 7617
6
IntelliJ IDE Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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 ]
 
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
These are not the droids you are looking for. Perhaps I can interest you in a tiny ad?
Gift giving made easy with the permaculture playing cards
https://coderanch.com/t/777758/Gift-giving-easy-permaculture-playing
reply
    Bookmark Topic Watch Topic
  • New Topic