Supponendo di avere questa classe (codice Java solo per motivi di esempio):
class Person {
private String name;
public void setName(String name) {
this.name = name;
}
}
Quando scrivo la documentazione per questa applicazione e / o la documentazione in codice, che cosa dovrei usare per fare riferimento a un particolare simbolo, che sia di tipo, metodo o campo?
Quando descrivo un tipo, di solito dico solo "Persona", mantenendo l'involucro del tipo. Quando faccio riferimento a un metodo, faccio sempre un punto: "Person.setName ()". A seconda del contesto, potrei aggiungere l'elenco dei parametri per essere tecnicamente corretto: "Person.setName (String)". Non cambio la notazione indipendentemente dal fatto che il metodo sia statico.
Ma il campo è un po 'più difficile e non sono sicuro, nonostante sia un programmatore da molti anni, di aver capito bene questa parte. Il mio cuore vuole sempre usare un carattere hash: "Nome persona". Ma credo che alcuni di noi usano l'uno o l'altro a seconda del contesto, indipendentemente dal fatto che il campo sia o meno statico? E se sì, quale personaggio usare quando?
Se si utilizza un punto, l'unica disambiguazione esistente tra un riferimento di campo e metodo è la presenza di due parentesi, che nella mia mente non sono sufficienti. Per esempio; "Person.name" è sintatticamente simile a "Person.setName ()". Ma non c'è comunanza, in termini di caratteri speciali, tra "Person # name" e "Person.setName ()". Inoltre, a mio avviso .. è il fatto che molti di noi sono sciatti e in realtà si riferiscono a metodi senza parentesi che rendono l'ambiguità assoluta.
Inoltre, se si suppone che il punto sia usato in riferimento a un campo, alcuni paragrafi di testo diventeranno piuttosto scomodi da leggere. Ad esempio:
Person is a class used in our application. A person has a Person.name. A person may also die.
Si noti che "nome" è circondato da un'esplosione di punti. Versus:
Person is a class used in our application. A person has a Person#name. A person may also die.
Tutti i feed back sono i benvenuti. La risposta che ha una fonte legittima o altrimenti parla di buone pratiche della comunità è accettata. Io personalmente, ho cercato su Google ma non ho trovato nulla.