Utilizzare un carattere hash o un punto quando ci si riferisce a metodi e campi nella documentazione del software? [chiuso]

3

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.

    
posta Martin Andersson 06.12.2015 - 18:37
fonte

2 risposte

5

In realtà, non si tratta di un sondaggio d'opinione, esiste una risposta chiara dettata dalle linee guida per scrivere i commenti dei doc e seguita dagli IDE.

Dal tuo codice di esempio è ovvio che stai parlando di Java.

Praticamente devi usare '#', poiché questo è ciò che è richiesto dallo standard, (vedi Oracle: Come scrivere commenti di un documento per lo strumento Javadoc ) e questo è l'unico modo in cui il tuo commento del doc sarà compreso dal tuo IDE, in modo che quando passi il mouse su una funzione chiama puoi vedere una bella descrizione che ti spiega cosa fa la funzione, quali parametri accetta e quale valore restituisce.

Lo standard di Oracle è un po 'obsoleto e ci piacerebbe molto vederlo sostituito da qualcosa di più moderno, ma finché ciò non accadrà, gli hash sono la strada da percorrere.

    
risposta data 06.12.2015 - 19:23
fonte
3

Mike Nakis ha scritto un'eccellente risposta Java centrica.

Per altre lingue, devi seguire le convenzioni stabilite in modo simile.

Ruby, ad esempio, utilizza "::" per i metodi di classe e "#" per i metodi di istanza.

Il punto, tuttavia, è semplicemente questo: non stai scrivendo la documentazione solo per il tuo consumo personale, ma per altri programmatori. Impara le convenzioni e gli standard per la lingua che stai utilizzando e attenersi a loro.

    
risposta data 06.12.2015 - 21:27
fonte

Leggi altre domande sui tag