Devo documentare gli operatori sovraccarichi in C #?

3

Quindi ho lavorato su una libreria C # Matrix. Finora l'ho documentato davvero bene.

Il fatto è che non so se dovrei documentare i miei operatori sovraccaricati, voglio dire, è abbastanza ovvio, non è vero?

Codice di esempio:

public static Matriz operator *(Matriz A, Matriz B)
{
    if (A.map.GetLength(1) != B.map.GetLength(0))
        throw new ArgumentException("A[j] não é igual a B[i]");

    float[,] _map = new float[A.map.GetLength(0), B.map.GetLength(1)];

    for (int i = 0; i < A.map.GetLength(0); i++)
    {
        for (int j = 0; j < B.map.GetLength(1); j++)
        {
            _map[i, j] = 0;
            for (int z = 0; z < A.map.GetLength(0); z++)
            {
                _map[i, j] += A.map[i, z] * B.map[z, j];
            }
        }
    }

    return new Matriz(_map);
}
    
posta Guilherme Almeida 29.06.2016 - 23:55
fonte

2 risposte

6

The thing is I don't know if I should document my overloaded operators, I mean, it is kind of obvious, isn't it?

Risposta semplice:

Quindi non ci vorrà molto tempo per documentarlo, vero? Fallo e basta!

Risposta complicata:

Stai scrivendo questa documentazione per da usare, non per se stessa. Per chi lo stai scrivendo? Come lo useranno? Qual è la loro opinione su ciò che rende la documentazione di qualità?

    
risposta data 30.06.2016 - 00:01
fonte
0

Un'ora di commenti sul tuo codice consente di risparmiare una settimana per coloro che cercano di aggiungere una funzione a un codice esistente. Non ho visto il codice troppo documentato oltre agli esempi di libri di testo.

The thing is I don't know if I should document my overloaded operators, I mean, it is kind of obvious, isn't it?

Può essere ovvio. All'autore Per un anno. Ma pensa ai nuovi arrivati che aggiungeranno funzionalità al tuo codice. Non è così ovvio per loro. Non hanno familiarità con il nostro stile. Potrebbero non conoscere alcune funzionalità linguistiche.

Ecco un esempio di Java: Lo stile delle parti vecchie e nuove è notevolmente diverso. Ad esempio, il codice più vecchio utilizza classi interne anonime, mentre il codice più recente si basa su lambdas. Sembra un mix di latino e italiano moderno.
I programmatori con diversi livelli di abilità e preferenze hanno stili molto diversi.
Le etichette della GUI non sono hard-coded (che è buono), ma sono memorizzate in diversi posti per ragioni storiche. Quindi, non è possibile cercare un progetto per un testo dell'etichetta.
Commenti minimi

In questa situazione ci vogliono diverse ore solo per arrivare alla classe, occupandosi di un elemento che si desidera modificare.

    
risposta data 30.06.2016 - 00:20
fonte

Leggi altre domande sui tag