[JAVA] Domanda sui commenti JAVADOC

[Yasha]

Ciao a tutti,
stavo realizzando un progetto per l'universita ed è richiesto di commentare i file in modo corretto, anche con i commenti javadoc.

Ora però mi viene un dubbio.
Io ho dei file con una classe public e magari altre classi nello stesso file.
Ex una classe che estende JPanel pubblica che contiene altre classi che estendono JPanel, queste sono nello stesso file ma non public.

In questo caso come dovrei commentare? Devo mettere ogni classe in un file separato?

Grazie

[andbin]

Originariamente inviato da Yasha
Ora però mi viene un dubbio.
Io ho dei file con una classe public e magari altre classi nello stesso file.
Ex una classe che estende JPanel pubblica che contiene altre classi che estendono JPanel, queste sono nello stesso file ma non public.

In questo caso come dovrei commentare? Devo mettere ogni classe in un file separato?

A livello di scrittura dei commenti Javadoc non cambierebbe niente. Cambia semmai il fatto che il tool javadoc per default (ma si può cambiare) considera solo classi/membri public o protected. Quindi se in un sorgente hai più classi "top-level" dichiarate, solo una, secondo le regole, può essere public. Pertanto per default javadoc non tratterebbe le altre con accesso package-level.

E il fatto di mettere ogni classe "top-level" in un sorgente a sé stante è l'approccio tipico/consigliato per rendere le cose più chiare e "pulite".

[VincenzoTheBest]

Originariamente inviato da Yasha
In questo caso come dovrei commentare?

Come si fa per una qualunque classe.

Originariamente inviato da Yasha
Devo mettere ogni classe in un file separato?

In questo caso è preferibile, però nessuno ti impone di farlo.

[Yasha]

Ti faccio un esempio:

/**
* ChooseListener e' un ActionListener che fa qualcosa.
* @author Author
* @version 1.0
*/

public class ChooseListener implements ActionListener {
...
}


/**
* AltroListener e' un ActionListener che fa qualcos'altro.
* @author Author
* @version 1.0
*/

class AltroListener implements ActionListener {
...
}

In questo caso i due commenti javadoc sono giusti? o è meglio seprare le classi in due file java?

[Yasha]

Originariamente inviato da andbin
A livello di scrittura dei commenti Javadoc non cambierebbe niente. Cambia semmai il fatto che il tool javadoc per default (ma si può cambiare) considera solo classi/membri public o protected. Quindi se in un sorgente hai più classi "top-level" dichiarate, solo una, secondo le regole, può essere public. Pertanto per default javadoc non tratterebbe le altre con accesso package-level.

E il fatto di mettere ogni classe "top-level" in un sorgente a sé stante è l'approccio tipico/consigliato per rendere le cose più chiare e "pulite".

Ops scusa Andrea, ho cliccato il link sulla mail e mi sono perso la tua risposta, quindi nel mio caso converrebbe dividere le due classi in file separati, essendo due listener diversi, che definirei top-level, giusto?

[andbin]

Originariamente inviato da Yasha
Ops scusa Andrea, ho cliccato il link sulla mail e mi sono perso la tua risposta, quindi nel mio caso converrebbe dividere le due classi in file separati, essendo due listener diversi, che definirei top-level, giusto?

Lo ripeto meglio.

L'approccio 1 sorgente per 1 classe "top-level" è solo, per convenzione, il modo standard e pulito per strutturare i sorgenti.

Nessuno ti vieta di tenere le due classi nello stesso sorgente a patto che:
1) Quella con accesso package-level ti serva solo in quel package (altrimenti non quadrerebbe).
2) Se vuoi che javadoc consideri i commenti di quella package-level, devi passare al tool javadoc l'opzione per far considerare anche il package-level.

E comunque, riguardo i "listener", il punto è che a meno di fare cose particolari o che debbano essere facilmente "riutilizzabili", la implementazione dei listener andrebbe fatta il più vicino e "internamente" possibile alla classe che gestisce la interfaccia grafica.

Se hai un MioFrame che estende JFrame, allora i listener andrebbero implementati lì dentro. A scelta (secondo il design) direttamente implementati in MioFrame o con una inner/nested class.

[Yasha]

Ok dovrei aver capito!

Grazie