Migliori pratiche di riepilogo dei metodi

Question

Migliori pratiche di riepilogo dei metodi

#1 da (4 voti)
#2 da (0 voti)
#3 da (-1 voti)

-2

Esistono best practice per i riepiloghi dei metodi?

Sono un po 'confuso su ciò che appartiene alla descrizione parametro e restituisce quando entrambi sono oggetti.

Ecco un esempio di un metodo che sto riassumendo:

public class DocumentRequestObject
{
        public List<UserIds> UserIds { get; set; } // User Ids being searched for document
        public string DocumentID { get; set; } // DocumentId being requested
}

public class DocumentReturnObject
{
    public string ResponseCode { get; set; } // Success, fail, etc.
    public string DocumentName { get; set; }
    public string DocumentType { get; set; }
}

public class DocumentService
{
    /// <summary>
    /// Returns a customer document summary object.
    /// </summary>
    /// <param name="request">A customer document request object that requires UserId(s) and the document Id being requested. </param>
    /// <returns>Response Code and document information.</returns>
    public DocumentReturnObject GetDocument(DocumentRequestObject dro)
    {
        // Some logic to search UserIds for requested DocumentId
        // Return DocumentReturnObject populated with details
    }
}

Questa deve essere una domanda basata sull'opinione pubblica; Semplicemente non sono riuscito a trovare alcuna informazione su Internet che risolva questo problema. Se questa è una domanda inappropriata per SE, fammi sapere. Grazie.

object-oriented design c#

posta EnterTheCode 17.05.2017 - 14:20

fonte

3 risposte

Leggi altre domande sui tag object-oriented design c#

Usare git su un progetto con aree diverse Posso copiare un progetto da CodePlex a GitHub [chiuso]

score 4 · Answer 1

Diamo un'occhiata al tuo esempio:

/// <summary>
/// Returns a customer document summary object.
/// </summary>

Lo so già guardando la firma del metodo.

/// <param name="request">The request object</param>

Lo so già guardando la firma del parametro formale.

/// <returns>The return object</returns>

Questo commento è così generico che in realtà ne so di più osservando il tipo di ritorno di quello che faccio dal commento.

/// <param name="request">
/// A customer document request object that requires UserId(s) and the document Id being requested. 
/// </param>

Questo è l'unico commento che potrebbe contenere effettivamente un frammento di informazioni utili. Tuttavia, cosa mi stai dicendo che non conosco già guardando la classe DocumentRequestObject ?

I commenti dovrebbero dirmi perché, non come o cosa il codice me lo dirà.

Se tutto ciò che stai facendo è ripetere i nomi dei tipi nei commenti, probabilmente stai meglio evitandoli del tutto e risparmiando il mal di testa della manutenzione.

score 0 · Answer 2

Non spiegare i membri degli oggetti di richiesta e risposta-- puoi spiegare quelli nei commenti di codice all'interno di quelle classi, e i commenti sono più propensi a rimanere aggiornati quando si trovano nella classe che documentano.

Spiega il comportamento esibito da GetDocument .

Non spiegare quali sono i tipi, dal momento che questi possono essere facilmente visti dallo sviluppatore.

Spiega cosa succede in casi limite significativi, ad es. se la chiamata non trova nulla.

/// <summary>
/// Gets a document from XXXX based on search criteria.
/// </summary>
/// <param name="request">Criteria for the search.</param>
/// <returns>A document matching the search criteria; null if not found.</returns>

score -1 · Answer 3

La migliore pratica è non perdere tempo nei commenti di riepilogo. Tuttavia, se sei costretto a farlo, ti consiglio qualcosa come:

/// <summary>
/// This is a method. It gets a document.
/// </summary>
/// <param name="request">The request object</param>
/// <returns>The return object</returns>
public DocumentReturnObject GetDocument(DocumentRequestObject dro)
{

}

Modifica: Solo per notare, molto spesso, una necessità percepita per i commenti di riepilogo è alleviata cambiando la firma del metodo per includere più informazioni.

public class CustomerDocumentService
{
    public DocumentInfo GetDocumentInfoForUsers(string documentId, List<UserIds> users)
    {
    }
}