• Post Reply Bookmark Topic Watch Topic
  • New Topic

Comment Errors In School Assignment  RSS feed

 
Graham McNallie
Greenhorn
Posts: 2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hey everyone. First post here so go easy please. My question is regarding the comments I'm being graded on in the exercise , which is pretty straightforward (instructions on the left)

As you can see in the picture I was marked against on both my Line and Javadoc comments.. My question is, what am I missing? Or what am I doing wrong here?

Exercise10CommentErrors.jpg
[Thumbnail for Exercise10CommentErrors.jpg]
 
Junilu Lacar
Sheriff
Posts: 11476
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Welcome to the Ranch!

Please don't post images when there's code involved. Post your code as text, properly formatted, and UseCodeTags (<--click that, it's a link) instead. The image you posted is of poor quality and the code is unreadable.
 
Junilu Lacar
Sheriff
Posts: 11476
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Refer to this document http://www.oracle.com/technetwork/articles/java/index-137868.html on how to write JavaDoc comments and see where you are not following the recommended style.
 
Graham McNallie
Greenhorn
Posts: 2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you for the link. I figured it out though it was a problem in format that wasn't mentioned in the textbook or on the Oracle page -  there was a space required after the beginning forward slashes and ending asterisk in the Block and Javadoc comments. I picked it up looking at the examples in the textbook, but is that standard? There is zero mention of it
 
Junilu Lacar
Sheriff
Posts: 11476
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I doubt there would be huge deductions made for minor spacing and formatting issues. If I were the teacher, I'd be more concerned with the content of the comment rather than the format. Focusing on minor formatting issues instead of comment content is like making sure that the lipstick isn't smudged and overlooking the fact that you just put lipstick on a pig.

If you would post your work so we can actually see it, we'd be able to give you our opinions. Again, post as text and UseCodeTags
 
Tony Docherty
Bartender
Posts: 3271
82
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Graham McNallie wrote: Thank you for the link. I figured it out though it was a problem in format that wasn't mentioned in the textbook or on the Oracle page -  there was a space required after the beginning forward slashes and ending asterisk in the Block and Javadoc comments. I picked it up looking at the examples in the textbook, but is that standard? There is zero mention of it

There is no requirement from the compilers point of view that there are spaces between the comment delimiters and the comment itself but having spaces does make the comment easier to read. Personally I always use spaces.
 
Tony Docherty
Bartender
Posts: 3271
82
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I've just looked at the image and I can't see why you haven't been given any marks for your line comment but it's hard to see detail in an image. The Javadoc comment is in the wrong place it should be before the main method declaration. Something like:
 
Junilu Lacar
Sheriff
Posts: 11476
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Forget my previous comment about lipstick on a pig. Tony's comment made me realize that I was trying to make out the details of the low-res "thumbnail" our forum software puts up. Clicking on the thumbnail takes me to the hi-res image. Again, for future reference, don't post images when there is code involved.

It's more likely that points were not awarded because of wrong placement, not so much the lack of spaces. As Tony said, spaces do make your code easier to read but placement and proximity of the comment to the code it pertains to is more important. All your comments are bunched up in a section that has no code below it. I'm actually surprised you got full marks for your block comment. In fact, since that block comment could also use some spaces and you got full marks for it anyway, I don't think that spacing was the issue at all.

JavaDoc comments are usually placed before a class, method, or field. You can also use a block comment where you would a JavaDoc comment but they are more commonly used before a section of code inside a method. Line comments are normally placed at the end of line or above a single line of code.

EDIT: Just for completeness, I think the program that is doing the checking answers to this is looking for a JavaDoc comment before the class declaration, a block comment before the main method, and a line comment before the call to System.out.println().

See the rest of this thread for my opinions on what you should be taught about comments; it's not this very superficial and unsubstantive stuff that you're being tested for.
 
Junilu Lacar
Sheriff
Posts: 11476
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
This is another example of how classroom instruction fails students by not focusing on the important things, or at least focusing on mechanics and form more than principle and substance. I think part of the problem is that teachers nowadays rely too much on automated systems to check students' work.

Here's what I would emphasize about comments:

1. Don't overdo them. Code that has too many comments is like a woman who's wearing too much jewelry and other accessories. Too many comments clutter up the code and make it more difficult to read. Too many comments tend to get ignored and collectively they are visually distracting. Just like a solitaire diamond around a woman's neck, the rare comment tends to stand out in code and draws attention to itself and the code around it. That's what you want, not a bunch of useless window dressing.

2. Before you write a comment, try to see if you can choose better names that help to clearly express the code's intent and purpose. See the following example:
versus
   
By choosing a more expressive name in the second version, you actually eliminate the need to write a comment. Prefer expressive code over comments. Comments can get neglected and often are not updated to reflect changes in the code. When that happens, comments can cause more harm than good because they are either misleading or entirely wrong.

3. If you have to write a comment, make it brief and to the point. The best comments tell WHY something was done.  The code should be expressive enough to self-document WHAT is being done and HOW it's being done. The worst comments are redundant comments that say nothing more than what the code already does.

Good comment that explains the reason behind a design choice:

Bad comment, says nothing useful:
 
Junilu Lacar
Sheriff
Posts: 11476
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Tony Docherty wrote:Something like:

I know Tony was just trying to give a quick example to show proper placement so don't take this as a knock on him. But let's focus on the substance of a comment like this because we don't want you to get the impression that this is actually a good comment because it's not.

If you refer to the Oracle article on JavaDocs, it notes that the first sentence of a JavaDoc comment should be a concise summary. The first sentence is your "headline" so it should be short but informative. For a main() method like this, something like "Entry point to the BestEver application." would suffice. For a main method, it's probably more important to document the arguments that the program will take since main() is pretty self-explanatory otherwise.

As for the @param comment, saying that args is an array of arguments is redundant. The next line of code make that obvious. Something like "args the command line arguments" would be better but it's still not much more useful, IMO. The idea is to let the code explain implementation details (that you have an array) and let the comment explain reasons/purpose/intent.

If the program does take command line arguments, the comment would be more useful if it continued after the @param to explain what each valid command line argument is and its purpose.
 
Junilu Lacar
Sheriff
Posts: 11476
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
You'd think that would be it but there's more and since I'm on a roll, might as well get this out, too.

End-of-block comments are also useless and serve only to create visual clutter and give the author of the code a false sense of accomplishment and being helpful to the reader. Below are examples of end-of-block comments.

To be honest, the above code would actually be relatively fine in that it's properly aligned and indented. A more typical example of the code we often see students post here would be something with atrocious formatting like this:

Granted, that's probably an extreme example but it's not very far off from the reality we often see in these forums.

The points here are:

1. Align your code properly so that its structure and organization is clear. Choose one of the common indentation styles for Java programs and follow it consistently.

2. Make your code blocks short so that it's obvious to the reader where they start and end without the help of end-of-block comments.

3. Use composed methods to keep your code blocks small.
 
Junilu Lacar
Sheriff
Posts: 11476
180
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
One last thing, going back to making code expressive to eliminate the need for comments. Take this example, based on Joshua Kerievsky's composed method example:

The comment is useless because it's exactly what the code itself says. This might be better:

At least the comment explains the significance of the comparison. It still talks about implementation details though by mentioning the "elements array." 

Here's a better way to make this code more readable:

Here, we got rid of the comment and extracted the formula (the detailed implementation) and replaced it with a method call. The method name we chose explains the purpose clearly and eliminates the need to add any comment.

If you study the composed method example carefully and understand the ideas and principles behind the simple changes you can make to get more readable code, you can get a lot better at writing good programs much more quickly than your peers.
 
Tony Docherty
Bartender
Posts: 3271
82
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
For that comprehensive set of instruction on comments you deserve a cow
 
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!