Change Set Comments

 

“It is amazing what one can accomplish if one does not care who gets the credit.” 

( Harry S Truman – tổng thống nghèo nhất trong lịch sử Hoa Kỳ)

As mentioned in SVN Best practices , the comments about change in source code (commit) is very useful for relevant people to keep track of the change.

Well, we don’t have to explicit write author name nor time in the comment, since any modern VersionControl tool always save the username and the last modified time. In older times our ancestors made some big headers for the lack of such features . Now it’s totally obsolete for source code files , just suitable for some config files which are not managed by a VCS/DMS/CMS .

 

.

Yet a funny thing is that there is quite a number of times I saw in the source code, the comments contain some Names/Nicknames, without any technical information (i.e. related to the code, or the change in the code) .

For example:

class Person implements Cloneable {
    private String firstName;
    private String lastName;

    public Object clone() {
        Person obj = new Person();
        obj.setFirstName(this.firstName); //linhlung
        obj.setLastName(this.lastName);
        return obj;
    }
    // Trivial getters and setters
}

(linhlung is the nickname of a freshman just joined the team)

or

//TuanXY added 
calculateTotalNumber();

(TuanXY is the name of a junior developer who joined the team for 2 months)

To be honest, I think those comments is a symptom of code smell, which is not only unhelpful to the code, but also promotes “Heroic” and “big ego” myth, and the eventual result will be something uncool.

 

.

Another similar feeling also came up in my mind when I saw somebody trying to create lot of files without substantial meanings (except for increasing complexity , and technical debt) , like this:

package my.project.selfpromotion

import org.apache.commons.lang.StringUtils

/*
 * @author khoaVietTiep
 */
public class StringUtils {
    public static void capitalize(String str) {
        org.apache.commons.lang.StringUtils.capitalize(str);
    }
}

. . .

 

.

Hopefully someday they will cultivate knowledge enough to get recognized/acknowledged in a glorier way . . .

 

 

./.