I collegamenti ripetuti alla stessa classe in un singolo commento di javadoc sono una cattiva pratica?

Question

I collegamenti ripetuti alla stessa classe in un singolo commento di javadoc sono una cattiva pratica?

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

3

Attualmente sto scrivendo un'API e la sua documentazione. Ad esempio, ho qualcosa di simile a questo:

public interface Event {
}

public interface Process {
}

public interface EventProcessor {
    /**
     * Starts to process the sepcified event asynchronously. The returned
     * {@link Process} can be used to track progress on the processing. If the
     * specified event causes more {@link Event events} to be processed in this
     * system, then they are also tracked via the returned {@link Process}.
     * 
     * @param event
     *            to be started to process
     * @return
     */
    Process startProcessing(Event event);
}

Nell'esempio sopra, il collegamento javadoc all'interfaccia Process viene ripetuto. Nell'API sto scrivendo ci sono casi in cui ho molti più riferimenti alla stessa classe in un singolo commento di javadoc.

Devo sempre contrassegnare i riferimenti alla classe / metodo / ecc. come collegamenti javadoc?

In generale, penso che avere molti link in un commento javadoc sia un segno di alta coesione. Ma quando spesso è lo stesso obiettivo, che è collegato, non sono sicuro se questo è buono.

coding-style programming-practices java documentation javadocs

posta SpaceTrucker 24.05.2013 - 16:00

fonte

2 risposte

1

Odio essere quello che ti dico, ma se davvero ( davvero ) ti preoccupi di ripetere allora è irrilevante quanti link ci saranno perché non importa cosa , i lettori di javadoc generati vedranno testo ripetuto due volte:

...returned Process can be used to track progress on the processing. If the specified event causes more events to be processed in this system, then they are also tracked via the returned Process

Quindi, prima di prendere decisioni complicate per collegare o non per linkare , è meglio decidere sulle basi: ti preoccupare di ripetere text o no?

Se decidi di non preoccuparti di ripetere il testo, è davvero più sensato non preoccuparti dei link: basta usarli come ti sembra più facile. È improbabile che i lettori che guardano testi ripetuti apprezzino i tuoi sforzi in merito alla coerenza nella presentazione dei link.

Se, d'altra parte, decidi di riformulare i documenti per evitare di ripetere il testo, questo risolve anche la tua preoccupazione riguardo alla ripetizione dei link.

Fai attenzione qui, perché fare un testo buono, facile da leggere e non ripetitivo può richiedere un notevole sforzo. In tal caso, considera la possibilità di coinvolgere qualcun altro per rivedere i tuoi documenti (generati, poiché questi appariranno diversi dalle origini di javadocs).

Se non hai il lusso di un recensore, fai delle revisioni di sé, cioè aspetta un giorno o due (meglio per una settimana o due), poi rivedi i documenti da solo - un nuovo look sarà quasi non proprio) come un altro paio di occhi.

risposta data 24.05.2013 - 19:57

fonte

Leggi altre domande sui tag coding-style programming-practices java documentation javadocs

Come implementare un tema per View Controller in un'app iOS? Diagrammi di comunicazione UML, dettagli di implementazione o no?

score 3 · Accepted Answer

Ecco quali sono le istruzioni oracle javadoc che dicono:

Use in-line links economically
You are encouraged to add links for API names (listed immediately above) using the {@link} tag. It is not necessary to add links for all API names in a doc comment. Because links call attention to themselves (by their color and underline in HTML, and by their length in source code doc comments), it can make the comments more difficult to read if used profusely. We therefore recommend adding a link to an API name if:

The user might actually want to click on it for more information (in your judgment), and

Only for the first occurrence of each API name in the doc comment (don't bother repeating a link)

Our audience is advanced (not novice) programmers, so it is generally not necessary to link to API in the java.lang package (such as String), or other API you feel would be well-known.

Quindi i collegamenti ripetuti e ripetuti allo stesso link target sono una cattiva pratica.

Grazie a @AaronKurtzhals per avermi indicato lì.