I commenti in prima persona sono distratti e non professionali?

I commenti dovrebbero essere scritti per essere compresi dagli esseri umani. Quando gli esseri umani comunicano, generalmente usiamo "io", "noi", "tu", ecc.

Quando qualcuno sta cercando di capire un po 'di codice, ci sono due o più attori: la persona che lo legge e l'autore originale del codice. Dire "noi" va bene. A meno che per "professionista" tu intenda "simile a un robot".

Suggerirei di evitare l'utilizzo di "I" perché assume automaticamente tutte le responsabilità per il codice. Se altre persone lo leggono, sarebbe un aspetto negativo perché in questo caso è uno sforzo di squadra. Sono indifferente sull'uso di "noi". Può, tuttavia, venire in grado di includere altri lettori in modo inusuale.

Il mio voto vale comunque per brevità e concisione. Se il messaggio può essere trasmesso in modo meno dettagliato, perché scegliere qualcos'altro? Quindi, per quanto riguarda questo esempio, vorrei scrivere:

'The form is not minimized so it can be resized safely.

Prendo uno dei due approcci, di solito solo quello che suona meglio.

Nello spiegare le cose come requisiti o giustificazioni, io vado con "noi" come tu hai lì:

// We can't proceed unless the user has given us this information.

Se sto spiegando il processo, tendo a usare una voce imperativa (comando) (correggimi se è il termine sbagliato):

// Get the foo from bar and make sure it follows our required format.

Quest'ultimo può avvicinarsi pericolosamente alla ripetizione del codice, ma ci sono degli usi. Quindi non sta usando io o noi, ma invece in realtà implica "tu".

Penso che sia solo una variazione dello stile di scrittura accademico / tecnico, che è spesso impersonale. Usando la voce passiva, usando il "royal we" ("uno" è così datato).

Come regola generale, è non specifico che lo userà comunque - il commento è per i manutentori, non normalmente solo per l'autore originale.

Detto questo, uso spesso la prima persona nei commenti - per spiegare perché I prendeva decisioni particolari, e cosa I stava pensando.

I commenti dovrebbero dirti perché qualcosa è stato fatto, non ciò che viene fatto. Se ciò che viene fatto non è ovvio dal codice, correggi il codice, non limitarti a aggiungere un commento. In prima persona, in seconda persona, ecc. Non importa, ciò che conta è comunicare le informazioni necessarie.

Se devi narrare il codice, preferisci gli imperativi, ad es.

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(E per favore non usare costanti nude come "1" nel codice)

Forse noi ci riferiamo ai piccoli ragazzi all'interno del programma che fanno accadere la magia? :)

La lingua inglese voce passiva è difficile da usare e suona male. Alle persone piace usare i moduli persona (io, tu, noi, uno).

Esempio:

(You/we/one must) use a delegate to pass window resize events to parent

A delegate has to be used for passing window resize events to parent

Un altro esempio (si noti che è spesso possibile omettere i moduli persona nei commenti):

(We) caught an exception. (We'll be) showing an error dialog.

An exception was caught and an error dialog will be shown.

PS. Sostituire il passivo con "tu" è così comune nella lingua inglese che ha iniziato a filtrare anche in altre lingue. Sembra estremamente divertente, ad esempio, in Finlandia, dove esiste la forma singolare della seconda persona (come l'inglese "tu").

Se stai parlando dell'esecuzione del programma, non è "noi", "tu" o "io". L'antropomorfismo può essere così diffuso da essere percepibile ma è un'abitudine pericolosa (Avviso PDF. Dijkstra Warning.):

I think anthropomorphism is worst of all. I have now seen programs "trying to do things", "wanting to do things", "believing things to be true", "knowing things" etc. Don't be so naive as to believe that this use of language is harmless. It invites the programmer to identify himself with the execution of the program and almost forces upon him the use of operational semantics.

Non penso che né la persona in prima persona né il "regale noi" sembrino poco professionali o distraggianti. Penso che dovremmo fare uno sforzo per scrivere commenti in inglese in E-Prime , il sottoinsieme di inglese che non possiede il verbo "to be".

Se si utilizza troppo "nei commenti" si ottengono affermazioni confuse come:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Bene, forse non tutto in una volta, ma l'is-of-equality può davvero rendere poco chiari i commenti.

Penso che i requisiti di scrittura in E-Prime contribuiscano a chiarire tali requisiti, in quanto lo scrittore deve indicare un attore insieme all'azione.

Lo stile corretto per i commenti è la terza persona impersonale; " Il modulo non è minimizzato, quindi può essere ridimensionato in modo sicuro ".

• I è ingenuo.
• Tu è crasso.
• Noi è troppo formale (e reale).

Ogni frase può essere riformulata in questo modo (vedi sopra) ed è l'unico modo professionale per scrivere.

Dipende dal commento.

In genere, scrivo commenti nel modo suggerito di The Mouth of a Cow . In questo modo, inoltre, scrivo sempre commenti di documentazione (Doxygen, JavaDoc).

Tuttavia, molti spesso trascurano l'uso del controllo di versione per identificare chi ha scritto / toccato le righe nei file di origine. Ci sono volte in cui dire "I" è appropriato, specialmente quando è abbastanza facile rintracciare l'io alla persona che ha scritto il codice. Se tu, come individuo, prendi una decisione, ti consiglio di usare "I" (insieme al controllo della versione) per identificare e tenere traccia delle decisioni in linea con il codice.

Il mio buon vecchio padre (mhrip) potrebbe chiedere: "Non hai cose più importanti con cui preoccuparti?"

Tuttavia, personalmente, mi piace il "noi". E mi sorprendo anche a chiedermi perché scrivo nei documenti up-stream, nemmeno nel codice, considerando che sono l'unico dipendente della mia azienda.

Tuttavia, io stesso e sono d'accordo che in questo modo ci sentiamo meno soli:)

Sono l'unico che scrive "noi" e pensa "io e il computer" (o "la mia squadra e il computer")? "Noi" gestiremo la richiesta che l'esterno ci ha dato, il che significa che "noi" dobbiamo leggere la richiesta, aprire alcune finestre, fare alcuni calcoli, in base ai "nostri" requisiti aziendali. Questo aiuta anche a vedere il codice come una parte della tua parte, non il nemico: -)

Per brevi commenti, a volte scrivo in seconda persona, come se stessi istruendo qualcun altro, quasi come un messaggio indirizzato al prossimo sviluppatore per leggere il commento. Ad esempio

//You can get a session_id from SYSSession.getSessionID() if you need one

Commenti più lunghi (come una lunga intestazione di funzione o più righe di descrizione dell'algoritmo) Provo a mantenere la neutralità, non la prima persona, la seconda persona o la terza persona.

Hai aggiunto questo commento perché il codice non era abbastanza chiaro. Generalmente trovo l'intenzione di esprimere attraverso metodi ben definiti che evitano l'uso di commenti. Ad esempio, quella riga potrebbe essere stata spostata in un metodo denominato CanThisFormBeResized .

Un metodo ben noto, per quanto piccolo, batte un commento, perché è facile che commenti e codice non siano sincronizzati.

Quindi, se la maggior parte dei commenti può essere espressa in codice, questo lascia ben pochi motivi per i commenti

• Se il tuo commento è la tua opinione, quindi inizia con "I"
• Se ritieni che il tuo commento debba essere un parere condiviso (ad esempio una best practice), quindi inizia con "noi"
• Se il tuo commento è diretto a un codice dodgy scritto da un mezzo-ingegno, poi scarta il commento e vai a dare un pugno a codice confuso da un collega, quindi affronta questo face-to-face con loro.

Come regola generale, suggerirei di utilizzare la prima persona, ovvero I .

Perché? Non a causa della natura possessiva di me, ma perché quando le persone parlano in una qualsiasi altra prospettiva, tendono a usare troppe parole o rendono le frasi troppo complesse, e si perdono nel cercare di spiegare le cose. La prima persona tende a essere sempre più facile da leggere.

Personalmente scriverei (in C #):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

O qualcosa del genere, quindi non ha bisogno dei commenti.