È corretto escludere i nomi degli argomenti dai prototipi di funzioni?

Question

È corretto escludere i nomi degli argomenti dai prototipi di funzioni?

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

3

Di recente stavo creando una piccola documentazione tecnica per un'applicazione. Il documento deve essere utilizzato dai nuovi programmatori per familiarizzare con l'applicazione. È molto più amichevole dei Javadoc che abbiamo e include informazioni che di solito non sono documentate.

Quando descrivo una funzione, prima porto il prototipo e poi la descrizione, l'uso, ecc. Devo scegliere di includere i nomi degli argomenti o di ometterli nei prototipi. Da una parte, i nomi degli argomenti sono per lo più banali (come MyClass myClass ), d'altra parte a volte contengono informazioni sullo scopo dell'argomento (che indicherò comunque descrivendo la funzione).

Ho avuto lo stesso dilemma in C ++ quando ho creato una classe in due file.

Devo includere i nomi degli argomenti? Funziona davvero per la leggibilità?

readability naming documentation

posta superM 13.03.2013 - 10:54

fonte

3 risposte

6

Se hai intenzione di generare documentazione dai file di intestazione, potrebbe essere una buona idea includere i nomi

risposta data 13.03.2013 - 11:22

fonte

-1

Includili dove ha senso e solo lì. Non è una scelta tutto o niente.

risposta data 13.03.2013 - 11:10

fonte

Leggi altre domande sui tag readability naming documentation

Vale la pena provare a scrivere strutture di dati infallibili? Questa situazione richiede associazioni ben definite, ereditarietà di una tabella singola o associazione polimorfica?

score 1 · Accepted Answer

Post-edit # 1 - la mia risposta funziona ugualmente bene per i nomi degli argomenti o per specificare il tipo di variabile, che è ciò che ho letto per prima come la tua domanda. La mia risposta è in parte motivata dal fatto che recentemente ho avuto una discussione simile con l'uso della parola chiave di auto-typing var di C # e un esempio di codice che abbiamo ricevuto.

Nella mia risposta "it" == argument name || variable type

Opzione A

Nei casi in cui è evidente dal tipo o dall'immediato prossimo utilizzo, procederei ed escludilo per ridurre la quantità da leggere.

Negli altri casi in cui fornisce informazioni importanti che non sono ovvie, dovresti includerlo.

Avvertimenti

Ciò che è ovvio per tu può o non può essere ovvio per il nuovo sviluppatore che legge la documentazione.

Se potrebbe cambiare, non includendo potrebbe nascondere il fatto che la documentazione è ora un po 'obsoleta. Al contrario, potrebbe effettivamente ridurre la velocità con cui la documentazione diventa obsoleta se passa da ObviousA a ObviousB .

Opzione B

Se hai bisogno di coerenza nella documentazione, dovresti sempre includerlo. Come hai affermato, ci saranno casi in cui non è ovvio, quindi se scegli tra "sempre" e "mai" poi vai con "sempre".

L'avvertenza all'opzione B è che si dà priorità alla coerenza rispetto alla potenziale leggibilità. È una prioritizzazione perfettamente valida, ma tu vuoi essere consapevole di prendere questa decisione.

post-modifica # 2 - se la mia risposta non è chiara perché ho cercato di essere troppo generico, faccelo sapere e provvederò ad adattarlo di conseguenza.