Commento sulla classe di interfaccia e sulla classe implementata entrambi? o solo la classe di interfaccia?

Question

Commento sulla classe di interfaccia e sulla classe implementata entrambi? o solo la classe di interfaccia?

#1 da (2 voti)
#2 da (1 voti)

1

Ora sto commentando sia sulla classe di interfaccia che sulla classe implementata. Ma a volte, ritengo sia inutile commentare entrambi. Quindi voglio sapere da Pro che è un modo migliore? commentando entrambi? o solo sulla classe di interfaccia?

Esempio)

/**
 * 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);
    }
}

coding-style

posta Expert wanna be 15.12.2016 - 09:35

fonte

2 risposte

1

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

Seriamente, per favore, per favore non farlo. I tuoi commenti aggiungono zero informazioni al file, ovvero sono al 100% di rumore e quindi rendono il codice più difficile da leggere. So che IGoogleAnalyticsService è una "interfaccia di servizio di Google Analytics"; lo dice nel nome. Quindi non dirlo anche in un commento.

Elimina tutto quel rumore e ci rimane:

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

E nulla è stato perso.

risposta data 15.12.2016 - 10:18

fonte

Leggi altre domande sui tag coding-style

Superare la manutenzione di un pacchetto software Qual è il modo migliore / più pitonioso di prendere in giro una funzione privata?

score 2 · Accepted Answer

Dipende ...

Io commento sempre entrambi e la maggior parte delle volte i commenti sono identici.

Pro: Quando ti immergi in un'implementazione concreta che non hai scritto è bello essere in grado di ottenere il contesto che i commenti forniscono senza passare all'interfaccia. Sono pigro e questo mi fa risparmiare 2 secondi.

Contro: La deriva dei commenti è reale. Se la tua squadra non è in grado di fornire commenti validi e / o di aggiornare tali commenti, può rapidamente sfuggire di mano.

Ho visto sviluppatori che usano i commenti per spiegare le implementazioni concrete. In sostanza, le implementazioni iniziano a diventare super funzioni nel tempo. I commenti vengono quindi utilizzati al posto delle responsabilità di refactoring. I commenti forniscono ancora valore qui, ma più come un segnale di avvertimento.

Quindi dipende in gran parte dall'abilità e dalla disciplina della squadra. Se si ridefinisce attivamente e si commenta bene, generalmente cado dalla parte di commentare tutto.