I commenti in prima persona sono fonte di distrazione e non professionale?

Mi sono appena trovato a scrivere il seguente commento in un codice (arcaico di Visual Basic 6.0) che stavo scrivendo:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

Non sono sicuro del motivo per cui inconsciamente uso "noi" nei miei commenti. Ho il sospetto che sia perché immagino che qualcuno passi attraverso il codice, come se stesse effettivamente "eseguendo" tutti i comandi su ciascuna riga, piuttosto che guardarli accadere. Con questa mentalità, avrei potuto usare I can resize it, dal momento che sono quello che lo sta "facendo" attualmente, o you can resize it, come se stessi parlando con chiunque lo "stia facendo" in futuro, ma dal momento che entrambi questi casi molto probabilmente succede, io uso "noi" come se guidassi qualcun altro attraverso il mio codice.

Posso semplicemente riscriverlo come it can be resizeded evitare il problema, ma ha suscitato la mia curiosità: è comune usare la prima persona in questo modo nei commenti o è considerato distratto e / o poco professionale?

I commenti dovrebbero essere scritti affinché gli esseri umani possano capire. Quando gli esseri umani comunicano, usiamo tipicamente "io", "noi", "tu", ecc.

Quando qualcuno sta cercando di capire un 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", intendi "robotico".

Suggerirei di non usare "I" perché si assume automaticamente tutte le responsabilità per il codice. Se altre persone lo leggono, sembrerebbe male perché in questo caso dovrebbe essere uno sforzo di squadra. Sono indifferente sull'uso di "noi". Tuttavia, può sembrare che includa altri lettori in modo non genuino.

Il mio voto vale ancora per brevità e concisione. Se il messaggio può essere trasmesso in modo meno dettagliato, perché scegliere qualcos'altro? Quindi, riguardo a questo esempio, scriverei:

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

Prendo uno dei due approcci, di solito qualunque cosa suoni meglio.

Nello spiegare cose come requisiti o giustificazione, vado con "noi" come 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 questo è 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 usi. Quindi non sta usando io o noi, ma in realtà implica "tu".

Penso che sia solo una variazione dello stile di scrittura accademica / tecnica, che è spesso impersonale. Usando la voce passiva, usando il "noi reale" ("uno" è così datato).

Come regola generale, non è specifico chi lo utilizzerà comunque - il commento è a beneficio dei manutentori, non normalmente solo per l'autore originale.

Detto questo, uso spesso la prima persona nei commenti per spiegare perché ho preso decisioni particolari e cosa stavo pensando.

I commenti dovrebbero dirti perché si sta facendo qualcosa, non cosa si sta facendo. Se ciò che viene fatto non è ovvio dal codice, correggi il codice, non solo 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 ci riferiamo ai ragazzini all'interno del programma per far accadere la magia? :)

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

Esempio:

(Tu / noi / uno devi) usare un delegato per passare gli eventi di ridimensionamento della finestra al genitore

È necessario utilizzare un delegato per passare gli eventi di ridimensionamento della finestra al padre

Un altro esempio (nota che spesso puoi omettere i moduli persona nei commenti):

(Abbiamo) preso un'eccezione. (Saremo) mostrando una finestra di errore.

È stata rilevata un'eccezione e verrà visualizzata una finestra di dialogo di errore.

PS. Sostituire passivo con "te" è così comune nella lingua inglese che ha iniziato a perdere anche in altre lingue. Sembra estremamente divertente, ad esempio, in finlandese, dove esiste la forma singolare in 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 impercettibile ma è un'abitudine pericolosa (Avviso PDF. Avviso Dijkstra.):

Penso che l'antropomorfismo sia il peggiore di tutti. Ora ho visto programmi "cercare di fare cose", "voler fare cose", "credere che le cose fossero vere", "conoscere le cose" ecc. Non essere così ingenuo da credere che questo uso del linguaggio sia innocuo. Invita il programmatore a identificarsi con l'esecuzione del programma e quasi gli impone l'uso della semantica operativa.

Non penso che né la prima persona né il "noi reale" sembrino poco professionali o distraenti. Penso che dovremmo fare uno sforzo per scrivere commenti in lingua inglese in E-Prime , il sottoinsieme dell'inglese che non possiede il verbo "essere".

Se usi eccessivamente "essere" nei commenti otterrai dichiarazioni confuse come:

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

Beh, forse non tutto in una volta, ma l'uguaglianza può davvero rendere poco chiari i commenti.

Penso che i requisiti di scrittura in E-Prime aiutino a renderli più chiari, poiché lo scrittore deve indicare un attore insieme all'azione.

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

• Sono ingenuo.
• Sei rozzo.
• Siamo troppo formali (e reali).

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 da The Mouth of a Cow . Scrivo sempre anche commenti generatori di documentazione (Doxygen, JavaDoc) in questo modo.

Tuttavia, molti spesso trascurano l'uso del controllo versione per identificare chi ha scritto / toccato le righe nei file di origine. Ci sono momenti in cui dire "io" è appropriato, specialmente quando è abbastanza facile rintracciare l'io alla persona che ha scritto il codice. Se tu, come individuo, hai preso 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) avrebbe chiesto: "Non hai cose più importanti con cui preoccuparti?"

Tuttavia, personalmente, mi piace il "noi". E mi trovo anche a chiedermi perché scrivo in documenti a monte, nemmeno in codice, considerando che sono l'unico dipendente della mia azienda.

Tuttavia, io stesso e sono d'accordo sul fatto 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, ciò significa che "noi" dobbiamo leggere la richiesta, aprire alcune finestre, fare dei calcoli, in base ai "nostri" requisiti aziendali. Questo aiuta anche a vedere il codice come parte del tuo lato, non come nemico :-)

Per brevi commenti, a volte scrivo in seconda persona, come se stessi insegnando a qualcun altro, quasi come un messaggio diretto allo sviluppatore successivo a leggere il commento. Ad esempio

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

Commenti più lunghi (come un'intestazione di funzione lunga o diverse righe di descrizione dell'algoritmo) Cerco di rimanere neutrale, senza prima persona, seconda persona o terza persona.

Hai aggiunto questo commento perché il codice non era abbastanza chiaro. In genere trovo che esprimere l'intento attraverso metodi ben definiti eviti l'uso dei commenti. Ad esempio, quella linea di potrebbe essere stata spostata in un metodo denominato CanThisFormBeResized.

Un metodo ben definito, 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, ciò lascia pochissime ragioni per i commenti

• Se il tuo commento è la tua opinione, inizia con "I"
• Se ritieni che il tuo commento debba essere un'opinione condivisa (ad esempio una buona pratica), inizia con "noi"
• Se il tuo commento è indirizzato a un codice non corretto scritto da una mezza astuzia, quindi scarta il commento e cammina oltre e dai loro un codice confuso da un collega, quindi affronta questo faccia a faccia con loro.

Come regola generale suggerirei di usare la prima persona, cioè I.

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

Personalmente scriverei (in C #):

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

O qualcosa del genere, non necessitando quindi dei commenti.