Comment on interface class and implemented class both? or interface class only?

Question

Now I'm commenting on both on interface class and implemented class. But sometimes, I feel it's unnecessary commenting both. So I want to hear from Pros which is a better way? commenting on both? or only on interface class?

Example)

/**
 * Google Analytics service interface
 */
interface IGoogleAnalyticsService {
     /**
      * Track an event
      *
      * @param { string } category category-name
      * @param { string } action action-name
      * @param { string } label
      * @param { number } value
      */
    trackEvent(category: string, action: string, label?: string, value?: number): void;
}

/**
 * Google Analytics service
 */
class GoogleAnalyticsService implements IGoogleAnalyticsService {
    /**
     * Track an event
     *
     * @param { string } category category-name
     * @param { string } action action-name
     * @param { string } label
     * @param { number } value
     */
    trackEvent(category: string, action: string, label: string = null, value: number = null) {
        this.$window.ga.trackEvent(category, action, label, value);
    }
}

score 4 · Accepted Answer · answered Dec 15 '16 at 09:07

It depends...

I always comment both and the vast majority of the time the comments are identical.

PROs: When you dive into a concrete implementation that you didn't write it is nice to be able to get the context that the comments provide without running over to the interface. I am lazy and this saves me 2 seconds.

CONs: Comment drift is real. If your team isn't good about providing good meaningful comments and/or updating those comments then it can get out of hand very quickly.

I have seen developers use comments to over explain concrete implementations. Essentially the implementations start to become super functions over time. Comments are then used instead of refactoring responsibilities. The comments still provide value here but more as a warning sign.

So it largely depends on the ability and discipline of the team. If you actively refactor and comment well then I generally fall on the side of commenting everything.

score 0 · Answer 2 · answered Dec 15 '16 at 09:18

/**
 * Google Analytics service interface
 */
interface IGoogleAnalyticsService {
    /**
     * Track an event
     *
     * @param { string } category category-name
     * @param { string } action action-name
     * @param { string } label
     * @param { number } value
     */
    trackEvent ...

Seriously, please please do not do this. Your comments are adding zero information to the file, ie it is 100% noise and so makes the code harder to read. I know IGoogleAnalyticsService is a "Google Analytics service interface"; it says so in the name. So don't say it in a comment too.

Strip out all that noise and we are left with:

interface IGoogleAnalyticsService {
    trackEvent(category: string, action: string, label?: string, value?: number): void;
}

And nothing has been lost.

Comment on interface class and implemented class both? or interface class only?

2 Answers2