Useful comments in your code

It's your first day at your new job. You get assigned a task from the backlog, which requires you to read tons of code so you can fix a small bug and therefore is an excellent way to become familiar with the codebase.

The bug is somewhere in the gardening subsystem, so you start looking at the code gardening modules.

You run into this:

/** The model for flowers */
interface FlowerModel {
}

And also this:

/** Represents a flower */
class Flower {
}

You keep digging and find out that the codebase is full of these self-referential useless pseudo-tautologies, which tell you absolutely nothing.

Wouldn't you find this infuriating if it happened to you? And yet, so many people do this. If you look at the git log for those files, you can probably glimpse a story more or less like this:

1. Code was committed with zero comments.
2. Reviewer asked for javadoc.
3. These comments were begrudgingly added.
4. Reviewer didn't care enough to ask for real, useful documentation and they were all in a hurry to deploy this so it was considered acceptable, or a promise was made to properly document that code later and of course that day never came.

Another possibility is that the comments were added like that from the start, maybe as a placeholder to add real documentation later. Maybe the person didn't even write those; they could have very well been generated by a plugin.

In any case, it's clear nobody thought of the person who would have to read this code for the first time, three years later, maybe even on their first day. It doesn't really tell them anything: what are flowers for? Where are they used? Why are they necessary?

So this person is now forced to go asking around a bunch of people, starting with the ones that git blame shows, and is keeps getting redirected to someone else until they finally ask someone who goes oooooooh, yeah, I remember that thing, wow, it was back when... and gets all starry eyed and tells a long story about how things were done back in the day, and it's probably very enlightening, but by now it's taken the better part of someone's day, when a simple paragraph describing the reason d'etre of the flower would have taken the writer less than an hour and the reader just a minute.

So, be mindful when documenting your code. Java programmers have at our disposal this nifty feature called Javadoc which allows us to add references to other declarations and other metadata. Even if you never generate actual docs from it, it's extremely useful when navigating code because IDEs can render javadoc on the fly, showing readers very useful information that saves a lot of time because they don't have to dive into other files all the time.

/** The contract for a component that
 * handles the storage of flowers.
 *
 * @see Flower
 */
interface FlowerModel {

    /** Inserts a new flower into the database.
     * Expects the flower to have no ID yet, and will assign a new one to it.
     * @param flower A new flower with no ID.
     * @throws DuplicateKeyException if a similar flower already exists
     *         (flowers are considered identical if they have the same scientific name)
     */
    void insert(@Nonnull Flower flower);

    /** Creates a group of flowers of the same kind.
     * @param flower The kind of flower to use
     * @param count How many flowers are included in the bouquet.
     * @returns A bouquet, which is a group of flowers of the same kind.
     * @throws IllegalArgumentException if count of less than 1.
     */
    Bouquet arrange(@Nonnull Flower flower, int count);
}

Ever heard that old saying about writing code as if a dangerous psychopath who knows where you live is going to read it five years from now? Well it applies for documentation too. But instead of writing out of fear, document your code out of empathy. Your future self will thank you when you go back to that code after a couple of years, and when the new hire documents their code properly too because they saw yours and took it as an example.