Win a copy of Design for the Mind this week in the Design forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Coding Convention - comments

 
Anna Hays
Ranch Hand
Posts: 131
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,

I read the coding conventions on the Sun website - http://java.sun.com/docs/codeconv/html/CodeConventions.doc10.html#182, I got the impression that each instance variable has to be commented and it is commented in the /* */ and /** */ style. I found this is very unreadable and uneccessary if the variable is self descriptive. Can someone tell me if the following comment style is acceptable please??


Thanks!
 
Kj Reddy
Ranch Hand
Posts: 1704
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Anna, you do not need comment each instance variable. Naming a variable self descriptive is more helpful. But you may need to do commenting with /** */ for documentation purpose wherever required.
 
Anna Hays
Ranch Hand
Posts: 131
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks.

What about private variables? // or /* */? /* */ looks consistent with /** */, but // looks neater.

Do you think this acceptable?

Or the style in my previous post?

Thank you!!
 
Kj Reddy
Ranch Hand
Posts: 1704
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Anna Kafei:
Thanks.

What about private variables? // or /* */? /* */ looks consistent with /** */, but // looks neater.

Do you think this acceptable?

Or the style in my previous post?

Thank you!!


If you want documentation for private variables then use /** */ type of comments.

Otherwise it depends on your judgement. For ex:
int int1 = 0; // integer 1

by seeing above line we know it is integer value, so I feel // integer 1 kind of comments not required.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic