Documenting intent Vs knowledge

Question

Documenting intent Vs knowledge

#1 da (5 voti)
#2 da (1 voti)
#3 da (1 voti)

2

Si dice che dovresti documentare l'intento della tua funzione o classe con la quale sono d'accordo. Tuttavia recentemente questa linea è diventata un po 'sfocata quando volevo che qualcuno documentasse perché questa particolare classe è stata creata.

Esempio specifico:

public class SMSException extends Exception{.....}

Nel caso precedente non vi è alcun codice aggiunto, ogni costruttore viene chiamato con super (...)

A chi ha familiarità con le eccezioni di lancio, la creazione di un'eccezione specifica per il lancio ha perfettamente senso. (che è il motivo per cui possiamo generare eccezioni come IllegalArgumentException, NumberFormatException ecc ... invece di solo Exception)

Documentare l'intento qui sembra fuoribordo dato che la documentazione sarà la stessa della classe che si sta estendendo ... Ma a volte sembra appropriato documentare questa conoscenza puramente in modo che quando i nuovi sviluppatori trovano ancora i loro piedi che si imbattono in questo possono capire perché questo è fatto e non solo mi chiedo perché le persone stanno facendo questo o quale sia il vantaggio di farlo.

Quindi la domanda: È buona pratica documentare qui quel po 'di conoscenza o questa conoscenza dovrebbe rimanere nelle sale delle lezioni, manuali di formazione, google, colleghi, ecc ...?

programming-practices java documentation

posta Riaan Schutte 19.03.2015 - 20:48

fonte

3 risposte

1

Direi che la conoscenza della documentazione è molto più incline a cambiare (specialmente se si ha voglia di documentarla) piuttosto che documentare l'intento. Quindi l'intento di documentazione è più efficace se si confrontano i due.

Ecco cosa intendo:

Quando parli di come si fa qualcosa ha due aspetti negativi:

1) It is not clear how you are doing something and so you are feeling compelled to explain it which in and of itself might be pointing you to a bigger problem.

2) When you decide to refactor how you are doing something your knowledge more often than not will become obsolete.

D'altra parte.

Quando documenta l'intenzione, c'è solo un lato negativo che a volte può essere giustificato.

1) Documenting intent shows that your code is not clear about its own intention and so you are feeling compelled to explain what it is doing. There are however times when it is okay to leave comments because you just have to solve it in a weird way and explain the intent.

Tuttavia, se decidi di effettuare il refactoring in un secondo momento, non cambierai le tue intenzioni, cambi solo il modo in cui viene eseguita la tua intenzione. Quindi il tuo commento non diventa obsoleto.

Suggerirei di documentare le cose ad alto livello da un punto di vista architettonico disegnando diagrammi ( draw.io è uno straordinario strumento che puoi anche integrare con JIRA se lo stai utilizzando nei tuoi progetti).

La ragione per cui è meglio documentare le cose da una prospettiva di alto livello è perché i dettagli spesso vengono rifattorizzati e la tua spiegazione richiede costantemente aggiornamenti ed emendamenti.

Una volta che l'architettura è compresa, il resto è molto più facile da afferrare e capire i dettagli.

risposta data 19.03.2015 - 21:11

fonte

1

Penso che "SMSException" sia ok come nome di classe, ma sicuramente potrei usare più spiegazioni su cosa significhi. Un errore nell'invio di un sms? Ricevendo uno? Analizzarne uno con un formato particolare? Non ricevendone uno quando previsto?

risposta data 20.03.2015 - 01:42

fonte

Leggi altre domande sui tag programming-practices java documentation

Utilizzo dei messaggi di commit per il monitoraggio del tempo Segnala come catturare lo scorrimento dell'ambito in iterazione

score 5 · Accepted Answer

Ritengo utile aggiungere una o due frasi per documentare l' utilizzo previsto della classe di eccezioni. Ad esempio, la documentazione di java.lang.ArrayIndexOutOfBoundesException indica:

Thrown to indicate that an array has been accessed with an illegal index. The index is either negative or greater than or equal to the size of the array.

Questa breve spiegazione viene scritta rapidamente e riduce notevolmente il rischio che la classe di eccezioni venga lanciata in modo incoerente. Mi aiuta anche a scrivere blocchi catch corretti per la tua classe di eccezione.

Per i costruttori deleganti, dovrebbe essere abbastanza ovvio cosa

public SMSException(String message);

documentarlo in modo esplicito potrebbe non meritare la massima priorità e potrebbe persino portare a un codice meno leggibile a causa di un rapporto segnale / rumore inferiore.