-1

I have a requirement, I want to put in-line/in-code comment to describe a line of code. e.g Using single liner comment 

private foo(List myNameList){
    for(String name :  myNameList){

     //This prints each element of list
      System.out.println(name);
     }
}

But many GREEN comments all over the code don't looks pretty.

I am just looking for an annotation or a solution to replace each comment with annotation e.g

private foo(List myNameList){
    for(String name :  myNameList){

      @Comment(n)
      System.out.println(name);

     }
   }

And just hovering over this @Comment should display my comment.

Note: In Comment(n) , n is an index of my messages/comments in some text file.

supernova
  • 3,111
  • 4
  • 33
  • 30

2 Answers2

1

Don't use either.

If you think you need to write a comment explaining what a piece of code does, don't write a comment at all. Refactor the code. Extract out small, well-named methods that break the logic down into understandable pieces.

Inline comments in code should be rare, and provide information that cannot be gleaned by reading the code: for example, why something happens.

See: What is self-documenting code and can it replace well documented code?

Community
  • 1
  • 1
Matt Ball
  • 354,903
  • 100
  • 647
  • 710
  • `Don't write the comments at all` is an ultimate solution every developer should strive for. This, plus `remove all the comments you have so far`. – MirMasej Sep 11 '15 at 15:57
  • Guys, I am looking for a solution to problem. Not best practices advice...please.. – supernova Sep 11 '15 at 16:00
  • @supernova how is "many GREEN comments all over the code don't looks pretty" a true problem? The ***root*** problem is one that should be addressed. Not a band-aid. – Matt Ball Sep 11 '15 at 16:01
  • 1
    Can you please provide a link to a "best practice" for why comments are bad. All I can find are best practice for "how to" write comments, some even saying that comments are required. – Andreas Sep 11 '15 at 16:02
  • @Andreas did you miss the link in my answer? – Matt Ball Sep 11 '15 at 16:03
  • 1
    I didn't and top answer says "writes a comment for each block of code that explains the intent". It does **not** say that you shouldn't write comments at all. – Andreas Sep 11 '15 at 16:03
  • 1
    Mostly , I write only comments to make it easy for new developer get a hint for some complicated logic. A line of comment can help future maintainers to get insight and save time understanding what's happening here. I think looking at comment is perspective. To me it was always helpful when reading others code with comments. – supernova Sep 11 '15 at 16:06
  • 1
    See [this article](http://blog.codinghorror.com/coding-without-comments/). Ideally comments should not exist with exception two cases: it's an API/SPI so someone will read the documentation without the source code and the documentation is generated from the comments, *or* there is information that comes from outside (like why something needs to be done like that which counter intuitive and violates LAP). Other cases are simply a result of writing bad code. – MirMasej Sep 11 '15 at 16:23
  • 1
    @MirMasej as mentioned in my earlier comment. I am really looking for a solution to the requirement and not suggestions, if commenting in code is good or bad practice. "Comments in code is good , bad or ugly ? " that is NOT my question! – supernova Sep 13 '15 at 06:05
  • @supernova I understand this and I respect your right to do whatever you want, ignoring suggestion to resolve the issue in other ways that you would like to. TBH I don't think there is solution to the requirement the way you want it, that's why people suggest other solutions that also could work. I proposed the closest solution I could think of (gray color for comments + folding). This is what I do while working with code I haven't written myself (i.e. containing the comments I never read anyway). – MirMasej Sep 13 '15 at 10:45
0

Assuming you're an Eclipse user (hence green comments) I think what you actually should do is to change syntax coloring instead of developing an annotation.

In Preferences go to Java -> Editor -> Syntax Coloring, unfold Comments in the box on the right and choose whatever color you want (I suggest gray) for each type of the comments.

Additionally in Java -> Editor -> Folding make sure to have Comments selected.

Alternatively you could just remove all the comments. But it won't do unless you write self explanatory code. Start from the useless one. Refactor where they explain hard to comprehend code.

MirMasej
  • 1,592
  • 12
  • 17