Still using @author for every file? Please don't...

Luke, I am Your Father!

In his first day at the new job, Bob created the following class:

import java.util.Arrays;
import java.util.List;

/**
 * Returns a sum of given numbers.
 * @author Bob
 */
public class NumberSumCalculator {
    public int sum(List<Integer> integers) {
        int sum = 0;
        if (integers != null) {
            for (Integer integer : integers) {
                sum += integer;
            }
        }
        return sum;
    }
}

He was so proud of it, so he put the @author Javadoc tag with his name at the top. Two days later, his friend Eve performed so called “cosmetic cleanup”:

import java.util.Arrays;
import java.util.List;
import java.util.Optional;

/**
 * Returns a sum of given numbers.
 * @author Bob
 */
public class NumberSumCalculator {
    public int sum(List<Integer> integers) {
        return Optional.ofNullable(integers)
                .map(list -> list.stream().mapToInt(Integer::intValue).sum())
                .orElse(0);
    }
}

Although she changed almost everything in the insides, she still appreciated Bob’s effort. What should she do now to not hurt his feelings?

• leave the @author tag untouched cause she doesn’t feel an author of this class?
• replace it with her name, because she changed almost everything?
• keep both names like this:

/**
 * Returns a sum of given numbers.
 * @author Bob, Eve
 */

or this:

/**
 * Returns a sum of given numbers.
 * @author Bob
 * @author Eve
 */

The only correct answer is: she should remove it completely!

This may look strange to you, but it’s not an abstract example. I’ve already seen it like thousand times - especially in mature and complex systems. Sometimes, usages of @author annotation are even more fancy - just look at this one:

/**
 * Some class - it does things.
 * @author Phil
 * @author Bob - Formatting change, important function extracted
 * @author Eve - IllegalArgumentException for incorrect args
*/

Remember feature envy code smell? In this case the Javadoc part is envy of Version Control System (VCS) capabilities. Just look into the git’s log - everything we want is already there! We can even check who, when and how changed each line using git blame (or with so called annotations in your IDE). Why is VCS is better for this kind of information? Because is reliable, always up-to-date and it does not pollute your code. And it’s already a part of your workflow, isn’t it? :-)

@author - seek & destroy!

Although Apache License already enforced the removal of author tags, the most popular Java IDEs - Eclipse and Intellij Idea still put similiar information for all new classes. Eclipse users will see standard @author tag but in Intellij, the default Javadoc looks like this:

/**
 * Created by Bob on 21.11.16.
 */

I strongly advise you to disable this behaviour right now - no matter what your favourite IDE is.

In my opinion, specifying author at the top of the file is useless and should be considered harmful for code readability. Think of it like those ugly “I was here” graffiti on the wall. These kind of “documentation” is misleading and becomes outdated almost immediately after the first change. To make things worse, someone may copy and paste the comment into the other class and mess around impersonating us ;-)

What about the rest of a Javadoc and comments in general? This topis deserves a separate explanation. In short words, the code should always speak for itself - any comments and documentation (if necessary) should only explain why not how.