aspose file tools*
The moose likes Beginning Java and the fly likes Need help putting comments in Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of The Java EE 7 Tutorial Volume 1 or Volume 2 this week in the Java EE forum
or jQuery UI in Action in the JavaScript forum!
JavaRanch » Java Forums » Java » Beginning Java
Reply locked New topic
Author

Need help putting comments in

Joey McGee
Greenhorn

Joined: Nov 22, 2012
Posts: 27
I need help finishing putting comments into my program, if anyone is willing to help me with that it would be greatly appreciated as I'm not that good at it . Also please double check my coding to make sure it's all correct. It compiles and runs correctly but that doesn't always mean the coding is 100% correct as I've found out.


fred rosenberger
lowercase baba
Bartender

Joined: Oct 02, 2003
Posts: 11246
    
  16

Nobody here is going to do your work for you. Put in the comments you think should be there. If you have questions about whether you've put in enough or too much, post that.

Also, there is really no way we can tell if your code is "all correct". You haven't given us any idea what this code is supposed to do.

Finally, if you say "It...runs correctly", that means it IS all correct. If you are not sure if it runs correctly, then tell us why you think that. Better yet, if you are not sure, then test it further yourself.


There are only two hard things in computer science: cache invalidation, naming things, and off-by-one errors
Joanne Neal
Rancher

Joined: Aug 05, 2005
Posts: 3456
    
  12
Comments should always be accurate.

Is the comment on line 10 of your Meal class accurate ?

What about the one on line 47 of your CateringCompany class ? If you replace that break by System.exit(0) does the code behave exactly the same ?

Joanne
Bear Bibeault
Author and ninkuma
Marshal

Joined: Jan 10, 2002
Posts: 61066
    
  66

In my opinion, comments such as "//constructor" and "//instance variable" are useless and superfluous. It's obvious that the following is the constructor or a variable; why does it need to be called out?

Comments should be used for one of 2 purposes:
  • To produce Javadoc for publicly callable methods.
  • To explain things that aren't obvious from the code.

  • Superfluous comments hinder code readability, and too many comments suffer from the "cry wolf" syndrome: the important comments get lost in the goop.

    The code can help be self-documenting by:
  • Using good names. Don't abbreviate needlessly: e.g. use status, not sts. (You actually do a good job of this in this example. The only one I'd question is numOfGuests; I'd use guestCount.)
  • Write the code for clarity; not cleverness.


  • [Asking smart questions] [Bear's FrontMan] [About Bear] [Books by Bear]
    Joanne Neal
    Rancher

    Joined: Aug 05, 2005
    Posts: 3456
        
      12
    Your getDiscount method can be simplified.
    You have two branches that return zero. See if you can come up with a test that handles both of those conditions in a single if statement. Hint: Only one comparison is needed.
    Once you worked that out, the first part of all your remaining if statements are superfluous as they will always be true.
    Joanne Neal
    Rancher

    Joined: Aug 05, 2005
    Posts: 3456
        
      12
    Your Event class is immutable (you can't change its state once you've created it. Therefore your grossPrice, discount and netPrice calculations in the toString method will always return the same value. I would therefore be inclined to do these calculations in the constructor which will only be called once rather than in the toString method where they will be calculated every time the method is called.
    Joey McGee
    Greenhorn

    Joined: Nov 22, 2012
    Posts: 27
    Joanne Neal wrote:Comments should always be accurate.

    Is the comment on line 10 of your Meal class accurate ?

    What about the one on line 47 of your CateringCompany class ? If you replace that break by System.exit(0) does the code behave exactly the same ?

    Not sure about the comment on line 10 of my Meal class... That's why I posted this here, so I could get help putting comments in my code. My teacher loves comments.
    Joanne Neal
    Rancher

    Joined: Aug 05, 2005
    Posts: 3456
        
      12
    Always try to avoid infinite loops (while(true)) with break statements in them.
    makes the purpose of the code a lot clearer.
    Joanne Neal
    Rancher

    Joined: Aug 05, 2005
    Posts: 3456
        
      12
    Joey McGee wrote:Not sure about the comment on line 10 of my Meal class

    Any comment that starts with TODO is just a reminder that there is some piece of code that you still need to write. But in this case you have written that code, so get rid of the reminder.
    Joey McGee
    Greenhorn

    Joined: Nov 22, 2012
    Posts: 27
    Joanne Neal wrote:Always try to avoid infinite loops (while(true)) with break statements in them.
    makes the purpose of the code a lot clearer.

    Not sure I follow... What is the . . . for in the code?
    Joey McGee
    Greenhorn

    Joined: Nov 22, 2012
    Posts: 27
    Joanne Neal wrote:Your Event class is immutable (you can't change its state once you've created it. Therefore your grossPrice, discount and netPrice calculations in the toString method will always return the same value. I would therefore be inclined to do these calculations in the constructor which will only be called once rather than in the toString method where they will be calculated every time the method is called.

    Not sure how to do that, any further help?
    Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 38412
        
      23
    Joanne Neal wrote:Always try to avoid infinite loops (while(true)) with break statements in them.
    makes the purpose of the code a lot clearer.
    My, that is so different from my suggestion.

    I also think one of the reasons we are going round in circles is that we have three simultaneous discussions. I am closing two, so as to force you to keep all the discussion in one place.
     
    I agree. Here's the link: http://aspose.com/file-tools
     
    subject: Need help putting comments in