Documentation for a Minecraft server plugin

Question

I'm working on a minecraft plugin for my Spigot Minecraft server.

I have a class which works as expected. I've done my best to hammer every single bug out (famous last words, I know) and am now taking a look at the way it's written. I've noticed that documentation definitely is not lacking, and looks over documented, to the point where it becomes unhelpful. My code is as follows:

package <redacted>;

import java.util.List;
import java.util.Random;

import net.md_5.bungee.api.chat.BaseComponent;
import net.md_5.bungee.api.chat.TextComponent;
import net.md_5.bungee.chat.ComponentSerializer;

import org.bukkit.entity.Player;
import org.bukkit.scheduler.BukkitRunnable;

import org.inventivetalent.bossbar.BossBar;
import org.inventivetalent.bossbar.BossBarAPI;

/**
 * 
 * @author Spotlight
 */
public class BossBarUpdate extends BukkitRunnable {

    private Player p;

    /**
     * Set global variables.
     *
     * @param p Player
     */
    public BossBarUpdate(Player p) {
        this.p = p;
    }

    @Override
    public void run() {
        // Cancel task if player logged off or crashed
        if (p == null || !p.isOnline()) {
            p = null;
            cancel();
            return;
        }
        if (!Main.SHOW_BAR) {
            // Do nothing, as AttentionManager or another class has taken over.
            return;
        }
        // Get list of possible messages
        List<String> messages = Main.barConfig.getStringList("messages");
        // Create color instance
        BossBarAPI.Color barColor;
        // Get current (first) boss bar
        BossBar firstBossBar = BossBarAPI.getBossBars(p).iterator().next();
        // Create possible string instance
        String possibleMessage;
        // Make current message a String
        BaseComponent[] components = ComponentSerializer.parse(firstBossBar.getMessage());
        String currentMessage = new TextComponent(components).toLegacyText();
        // Choose a random color + message
        do {
            // Get random color
            barColor = new Utils(null).randomEnum(BossBarAPI.Color.class);
            // Get random number between message size
            int index = new Random().nextInt(messages.size());
            // Get random message at random number index
            possibleMessage = messages.get(index);
        } while (!firstBossBar.getColor().equals(barColor) & currentMessage.equals(possibleMessage));

        TextComponent message = new TextComponent(TextComponent.fromLegacyText(possibleMessage));
        // Temporarily reset bars
        BossBarAPI.removeAllBars(p);
        // Choose a random color
        BossBarAPI.addBar(p, // The receiver of the BossBar
                message, // Displayed message
                barColor, // Color of the bar
                BossBarAPI.Style.PROGRESS, // Bar style
                1.0F); // Fullness
    }
}

I'm looking to increase the helpfulness of this code's documentation, so that it's not as verbose, but you can still tell what's going on. All comments are welcome, even if they aren't related to documentation.

Answer 1

First of all, there is a dinstinction between comments and documentation.

• Documentation (Javadoc) defines the contract of what it documents. The Javadoc on a class, for example, describes what the purpose of the class is and can even give examples on how to use it. On a method, Javadoc describes what the method should be used for, along with its parameters, return type, potential exceptions... This documentation is not embedded directly in the code, but on top of it, as specification.
• Comments are private; they are inside the code itself and clarify how the implementation is working.

If you want an example, you can look at the Javadoc for the HashMap class and you can then peek into the comments inside the implementation. Both describe completely different things, because they target different issues: the documentation specifies the class, the comments explain the implementation.

---

You are right that most of the comments are unhelpful and mostly useless. The point of a comment is to clarify the intent of the code; that is to say, not repeat it, but explain why it is doing what it is doing.

As an example, you currently have:

// Create color instance
BossBarAPI.Color barColor;
// Get current (first) boss bar
BossBar firstBossBar = BossBarAPI.getBossBars(p).iterator().next();

1. The first comment is, in fact, misleading as it says that the code is creating a color instance, when, in fact, it is not. It is just declaring a new variable barColor without initializing it.
2. The second comment is just a repeat of the code. If there were something to comment here, it would not be that we're getting the first boss bar (which the code iterator().next() already conveys sufficiently clearly); it would explain why we're getting the first boss bar to begin with.

Another example is:

BossBarAPI.addBar(p, // The receiver of the BossBar
        message, // Displayed message
        barColor, // Color of the bar
        BossBarAPI.Style.PROGRESS, // Bar style
        1.0F); // Fullness

Having a comment on every parameter is too much. This should normally be documented properly with Javadoc on the addBar method, which would explain what each parameter is. An IDE can then simply show this Javadoc (on hover for example), which will actually give more information that those short comments.

However, there are useful ones:

if (!Main.SHOW_BAR) {
    // Do nothing, as AttentionManager or another class has taken over.
    return;
}

Arguably, it isn't directly obvious that doing nothing at that place was the intention. The comment clearly explains why it is the case and helps future developers: they won't need to scratch their head wondering why this code is there.

---

That said, you are really missing the most important documentation of all, which is the Javadoc.

• The class BossBarUpdate doesn't have any.
• The constructor of BossBarUpdate "Set global variables", without mentioning what those variables are, what they are used for or what the single parameter Player p is for.
• The public method run() is also without documentation. How are users of that class supposed to know what it does?