Proper Commenting

Discussion in 'Plugin Development' started by zachoooo, Nov 13, 2012.

Thread Status:
Not open for further replies.
  1. Offline

    zachoooo

    Hey everyone, I was wondering about the best way to comment code. Whenever I look at Bukkit's source, I notice how virtually everything is commented. Is there an official format or way of commenting?
     
  2. Offline

    CorrieKay

    i use two different ways to comment.

    //this is a line comment. Use it to explain a single line. Typically placed before a line, or at the end of a line.
    Side note, if you ever need to place a "bookmark" so to speak, type //TODO <what you need to do> and eclipse will throw a little line in the scroll bar at all your TODO's to denote that you need to finish something up there.

    /*
    * This is a documentation comment
    * Use it to explain in detail a specific method,
    * Block of code, or even
    * An entire class.
    */

    Also, tip, if you type /* then hit enter, eclipse will automatically put the */ in the line after, and whenever you linebreak, it will automatically put a * before the line.

    So if you type /* then hit enter, it will look like this

    /*
    * (cursor here)
    */

    side note, if you put a double asterisk (/**) that acts as javadocs commenting. Also, there is no actual need for the asterisks per line.
    /*
    This works just fine too
    */

    Which is also a really easy way to comment out large blocks of code. You can see an example of that here.
     
    zachoooo likes this.
  3. Offline

    ZeusAllMighty11

    CorrieKay

    What about stuff on GitHub sources that says like:

    /*
    * @Author
    */

    What does that mean?
     
    zachoooo likes this.
  4. Offline

    Malikk

    Those are tags that define certain headings in a javadoc. Afaik, all it changes is the formatting of the doc for that method/class.

    @Author simply makes it print Author: whoever.

    If I'm totally wrong and there's more of a point to it than that, someone correct me.
     
Thread Status:
Not open for further replies.

Share This Page