• Post Reply Bookmark Topic Watch Topic
  • New Topic

Coding style  RSS feed

 
Stuart Smith
Ranch Hand
Posts: 54
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Just reading through examples on this site and various tidbits and would like to know if I have the style right?

Thanks


[ March 28, 2008: Message edited by: Stuart Smith ]
 
Mark Vedder
Ranch Hand
Posts: 624
IntelliJ IDE Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Looks good to me
 
Mark Vedder
Ranch Hand
Posts: 624
IntelliJ IDE Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
oops - just noticed one small thing. The class' opening comments and the method comments should be Javadoc Style comments, not inline style. So you want this:



Note that Javadoc comments start with a slash and double asterisks "/**" - the javadoc tool (which generates the actual Javadoc documents from the code) uses the /** to know that the comments are Javadoc comments and not coding comments.

Also, typically it is customary that the description comes first, and then the various tags such as @author and @param (which I added for your main method).

And lastly, you want the first line/sentence of a Javadoc comment (whether for a class, method, or instance variable) to end in a period (notice that I added that). The Javadoc tool that generates the Javadocs uses that punctuation to determine what the first summary line is. That summary line will appear as, you guessed it, a summary in various indexes and table of contents, as well as the member summary at the top of the page. (Now if you want to be absolutely technical, your comments would be ok without the period since the entire comment (before any block tags like @author) is only one sentence, and the javadoc tool would use it as the summary. But good practice would say to have the period.)

You can learn more about Javadocs at: http://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html and, of course, view the JavaDocs for Java 6 itself at http://java.sun.com/javase/6/docs/api/

Hope that helps
[ March 28, 2008: Message edited by: Mark Vedder ]
 
Stuart Smith
Ranch Hand
Posts: 54
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks for that, I want to get it right from the off and I have learned some usefull things about the way that the JavaDoc works, thanks for the links also
 
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!