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?
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.
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
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.
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.
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:
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:
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.
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.
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.