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);
    }
}
  • 2
    Possible duplicate of DRY way to write Javadoc on overload methods – gnat Dec 15 '16 at 8:37
  • That depends... I usually only comment on interface, since that's what I'm expecting in "client" constructors... – kayess Dec 15 '16 at 8:41
  • I write a comment in the interface. And in the implementing class only if I think something additional to the documentation of the interface should be done. E.g. Sometimes I document in the implementing class things like the complexity of the operation. – MrSmith42 Dec 15 '16 at 8:56
  • Also, if you don't have anything of substance to say, don't add a comment/documentation. Your example is fully redundant with the function signature. – CodesInChaos Dec 15 '16 at 9:24
up vote 2 down vote accepted

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.

/**
 * 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.

  • 1
    I up voted but the solution here should be to provide verbose and meaningful comments not to remove them all (= . This illustrated well that auto-generated comments aren't even worth the disk space though. – Adrian Dec 15 '16 at 9:26

Your Answer

 

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.