Iniziando una frase con un nome di funzione? [chiuso]

42

Occasionalmente durante la digitazione di qualcosa che si riferisce a un linguaggio di programmazione con distinzione tra maiuscole e minuscole, finisco per iniziare una frase con un nome di funzione. Ora le regole dell'inglese affermano che la prima parola di una frase deve essere maiuscola; il nome della funzione è in minuscolo, però. Se ti stai chiedendo cosa potrei dire che si tradurrebbe nella prima parola come nome di una funzione, prendi questo esempio:

L'implementazione della fread è interrotta. fread deve restituire quanti byte sono stati letti.

Capisco che potrei cambiare la seconda istanza di fread in It, ma voglio sapere il modo migliore di gestirlo oltre a riscrivere la frase. Devo scrivere in maiuscolo il nome della funzione? L'unico modo in cui vorrei sentire "riscrivi la frase" come risposta è se iniziare la frase con un nome di funzione viola alcune regole inglesi di cui non sono a conoscenza. Modifica: ringrazio davvero tutti per queste risposte. Hanno cambiato e migliorato la mia visione del problema. Ho imparato parecchio da questo. Sono molto sorpreso di non aver pensato a queste soluzioni semplici ma buone.

Penso che la mia posizione sull'alternanza della frase fosse troppo dura e ora mi rendo conto a causa di queste buone risposte che l'alterazione complessiva della frase sembra essere l'opzione migliore per affrontare questi casi, sia aggiungendo parentesi dopo la funzione o dicendo La funzione prima del nome della funzione e se disponibile usando la formattazione per il nome della funzione.

functions

— user3462295
fonte

1

@gnat Non sto chiedendo come nominare qualcosa, sto chiedendo come iniziare una frase con un nome di funzione.

— user3462295

13

Esiste una convenzione correlata in matematica che si dovrebbe evitare di iniziare una frase con un nome o una formula variabile. Questo nonostante il fatto che abbiamo una convenzione tipografica secondo cui variabili e formule sono rese in corsivo per allontanarle dal testo. Si eviterebbe di scrivere "Sia x una potenza di 2. x è positivo, quindi ..." La solita correzione è riformulare o aggiungere qualche parola di riempimento: "Ora x è positivo" o "Abbiamo che x è positivo" o qualcosa del genere.

— Nate Eldredge,

9

Un identificatore di un linguaggio di programmazione dovrebbe essere trattato come una parola straniera e non dovrebbe essere soggetto alle stesse regole dell'inglese.

— Rufflewind

1

Ci sono alcuni programmatori straordinariamente attivi su English.SE ( tchrist ... non tanto Eric Lippert ) - ma dipende dal tipo di risposta che desideri. Stiamo scrivendo questo come programmatori su un sito focalizzato sul programmatore. Se sei più interessato alle formalità della scrittura tecnica, alle linee guida del diario e alla corretta struttura delle frasi in inglese, potresti voler riconsiderare il tuo pubblico di esperti target.

2

Questa domanda sembra fuori tema perché è la lingua inglese e l'utilizzo, e abbiamo un intero sito StackExchange per quello. In effetti, ci sono almeno quattro domande simili lì . Inoltre, risposte diverse possono essere ugualmente valide a seconda di dove appare la scritta, ecc.

— Caleb,

87

Nella tipografia questo viene generalmente gestito usando un rendering diverso, indipendentemente dal fatto che sia l'inizio di una frase, per indicare che ciò che colpisce l'occhio non è solo una parola nella frase ma un'entità speciale.

L' freadimplementazione è stata interrotta. freaddeve restituire quanti byte sono stati letti.

A seconda di quanto sia formale un documento, può adottare lo stesso approccio. In ogni caso, così facendo elimini il problema che identifichi, quindi potresti volerlo usare solo per quel motivo.

Nel mondo del testo semplice (come notato da molti in commenti e altre risposte), aggiungere parentesi ai nomi delle funzioni aiuta un po ', ma poiché dobbiamo anche fare riferimento a entità che non prendono parentesi, questo ha solo un valore limitato. In generale, a parte l'adozione di una convenzione che circonda il testo con caratteri speciali come parentesi quadre e asterischi, nel mondo del testo in chiaro ci sono poche opzioni se non eludere la questione ristrutturando la frase.

— Modifica reg
fonte

Sì, vedo il tuo punto, rimane comunque imbarazzante ma meno imbarazzante. Tuttavia capisco che i sentimenti non sono sempre in linea con le regole della grammatica e della scrittura. Non sono sicuro che esista un modo migliore per gestirlo, quindi accetterò la tua risposta a meno che qualcuno non abbia trovato qualcosa di meglio.

— user3462295

25

Spesso mi limito a scrivere in corsivo cose come queste: dovresti sempre mantenere il maiuscolo / minuscolo, indipendentemente da dove si trovano in una frase, IMO. freadnon è una parola; è un simbolo che rappresenta un'entità. Non è soggetto alla grammatica.

— Formica P

4

E ... cosa fai se hai a che fare con il testo normale? Come in un piccolo file di aiuto .txt o in una semplice e-mail di testo? Suggerisco di includere anche quello scenario alla tua risposta.

— Ellesedil,

2

@Ellesedil In tal caso, in genere lo suffisso ()o (...)per indicare che è una funzione. Ma ciò non sempre funziona, soprattutto quando si tratta di variabili e simili. Quello che faccio allora è avvolgere il nome con `(segno di spunta) per indicare il suo codice.

— Cole Johnson,

4

@Ellesedil Ho iniziato a usare la sintassi di markdown per indicare elementi di codice, anche in contesti di testo semplice come i commenti. È l'unica volta in cui abbia mai avuto bisogno di usare un simbolo di backtick quando scrivevo un inglese semplice.

— Appassionato il

53

Se è assolutamente necessario iniziare ogni frase con un limite, è sufficiente sostituirla freadcon "La freadfunzione" ovunque inizi una frase.

— x-code
fonte

21

Se non hai mezzi tipografici per distinguere (come per un'altra risposta), e forse anche se lo fai, può essere utile indicare che stai parlando di una funzione usando le parentesi:

L'implementazione di fread () è interrotta. fread () deve restituire quanti byte sono stati letti.

Questo aiuta con "spiegare" perché non è capitalizzato all'inizio della seconda frase, e aiuta anche (nella prima frase) per capire il motivo per cui il nome proprio (nome di una funzione) non è lì in maiuscolo sia . Dal momento che (come un nome proprio) avrebbe probabilmente dovuto essere.

("discutibilmente" perché potremmo discutere se fread () è un nome generico o un nome proprio).

Nel complesso, l'uso delle parentesi aiuta il cervello del lettore a capire perché compaiono strane parole e quali sono.

— GreenAsJade
fonte

5

L'uso delle parentesi aiuta anche a ridurre la ridondanza del testo. Invece di "la funzione fread" puoi dire solo "fread ()". Ed è anche utile se hai una sorta di evidenziazione per enfatizzare la differenza tra cose come nomi di variabili e funzioni.

— Paul92,

3

Penso che le parentesi aggiungano solo più confusione. fread()potrebbe essere un'istruzione call. Oppure potrebbe riferirsi a una funzione sovraccarica senza parametri.

— Kapex,

4

@kapep Generalmente nei documenti che si riferiscono al codice, func_name()viene letto come "una funzione con il nome func_name", indipendentemente dal fatto che la funzione stessa abbia o meno dei parametri.

— Eric Finn,

3

@EricFinn Nella mia esperienza in genere fa riferimento a funzioni senza parametri, ma dipende sicuramente dal linguaggio e dalle sue convenzioni. Ad esempio, le linee guida ufficiali per i commenti su Java scoraggiano l'uso delle parentesi: "Quando si fa riferimento a una [forma specifica di un metodo], utilizzare parentesi e tipi di argomenti. [...] Tuttavia, se si fa riferimento a entrambe le forme del metodo, omettere le parentesi del tutto. È fuorviante includere parentesi vuote, perché ciò implicherebbe una forma particolare del metodo " oracle.com/technetwork/java/javase/documentation/…

— kapex

3

Mentre aggiungere un indizio visivo è sicuramente una buona idea (il migliore è un font dedicato o altrimenti evidenziare), sono d'accordo con kapep che aggiungere parenti vuoti è una scelta davvero problematica, perché in ogni lingua che conosco f()significa qualcosa di diverso f. Perché non racchiudere il nome con un carattere adatto, ad esempio "fread" in stile markdown (è quello che tendo a fare nei messaggi di commit VCS)? O semplicemente (fread). Naturalmente, qualsiasi cosa del genere dovrebbe essere fatta in modo coerente, non solo per le funzioni all'inizio di una frase.

— leftaroundabout

10

Puoi iniziare la frase dalla descrizione:

La funzione fread[…]

Il metodo fread[…]

La proprietà breadColor[…]

— David Sergey
fonte

@Zack: Presidente Obama.

— Marc van Leeuwen,

@MarcvanLeeuwen I titoli sono un caso speciale. (Anche "Queen Elizabeth", "Mister Rogers".) Non ho un'analisi corretta dalla cima della mia testa, ma intuitivamente penso che siano considerati parte del nome piuttosto che un tag di categoria.

— zwol,

8

È possibile confrontare questo per incorporare la matematica nelle pubblicazioni. Molto raramente vedrai delle frasi che iniziano con una variabile o altra matematica in linea.

Quindi, concludo, dovresti evitare i nomi delle funzioni all'inizio di una frase.

Forse questa domanda fornisce ulteriori dettagli: va bene iniziare una frase con una lettera greca (variabile)? .

— Lukas
fonte

3

+1. In Mathematical Proofs (Chartrand et al., 2000), il cui capitolo 0 è una vera fonte di buoni consigli per la scrittura matematica, la prima regola in Uso dei simboli è "Non iniziare mai una frase con un simbolo". (L'esempio è una frase che inizia con un'equazione; gli autori suggeriscono di sostituirla con "L'equazione ___".) Sebbene non tutti i consigli di scrittura matematica si applichino necessariamente alla scrittura sul codice sorgente, penso che questo sia un bit che lo fa.

— Ruakh,

1

Non sono sicuro di essere d'accordo con l'analogia. Simboli come $ x $ sono transitori a un'equazione, quindi è strano riferirsi a loro come se avessero un significato globale. Se un simbolo come $ \ pi $ inizia una frase, mi sentirei a mio agio come lettore.

— djechlin,

1

@djechlin Non sono sicuro che iniziare una frase con un simbolo implichi che abbia un significato globale o che in effetti non abbia nulla a che fare con questo.

— Kyle Strand

@KyleStrand sarebbe bello sapere perché non dovresti mai iniziare una frase con un simbolo. "$ \ pi $ è ..." v. "La costante matematica $ \ pi $ è ..." - tu scegli.

— djechlin,

1

@djechlin: Uno dei motivi è che se la frase precedente termina con la matematica, la matematica all'inizio della frase seguente potrebbe apparire come parte della stessa formula con un punto in mezzo. (Questo è ancora più un problema con le virgole.) Un altro problema è che poiché i nomi delle variabili sono generalmente minuscole, l'occhio del lettore perde l'indizio visivo di cercare una lettera maiuscola per trovare l'inizio della frase successiva.

— Nate Eldredge,

3

La pagina man di Linux per fread (3) che altri hanno collegato è un ottimo esempio di quattro soluzioni comuni.

Inizia la frase con "La funzione foo" o "La funzione foo". "La funzione fread deve tornare ..." .
Contrassegnare il nome della funzione con caratteri aggiuntivi in base alla convenzione utilizzata dalla comunità del linguaggio di programmazione. Nel caso di C, una coppia di parentesi vuota, quindi "fread () deve tornare ..." .
Usa la tipografia (grassetto, caratteri a larghezza fissa o corsivo) per evidenziare il nome della funzione, come: " fread deve tornare ..."
Sui sistemi che usano man, se la tua funzione ha una pagina man, fai riferimento al capitolo del manuale tra parentesi. Quindi "fread (3) deve tornare ..."

Tutti e quattro gli approcci saranno immediatamente riconoscibili dagli hacker e dovresti essere in grado di sceglierne uno che corrisponda al tuo stile di casa o alla tua voce personale.

Come hai detto, non puoi fare affidamento sulla tipografia per evidenziare il nome della tua funzione. La sintassi di Markdown ha lo scopo di rendere la documentazione leggibile anche quando un interprete markdown non è disponibile, quindi circonda il nome della tua funzione con una coppia di backtick. (Credo sia una combinazione di opzioni 2 e 3.)

L'opzione 2 varia in base al linguaggio di programmazione. Ad esempio, i documenti Ruby e Smalltalk spesso precedono i nomi dei metodi di istanza con un hash, come #fread . Nel frattempo, Lispers potrebbe preferire che il nome della funzione sia nudo, ma capirà se si scrive una chiamata di funzione scheletro, come (fread ...) o (fread) . Risciacquare e ripetere per tutte le lingue documentate.

— dcorking
fonte

Mi piace la tua risposta. In questo modo la scrittura delle funzioni sembra migliore.

— user3462295

2

Risponderò solo per l'esempio specifico fornito:

L'implementazione della fread è interrotta. fread deve restituire quanti byte sono stati letti.

Sostituisci il primo punto (punto) con un punto e virgola:

L'implementazione della fread è interrotta; fread deve restituire quanti byte sono stati letti.

— EdHunter
fonte

3

No! che lo renderebbe una frase di esecuzione o una virgola. Grammatica molto scarsa. Un punto e virgola sarebbe OK.

— Martin McCallion,

Quindi usare una virgola non funziona sempre; ma perché usare una virgola?

— reinierpost,

Non è una virgola. È un punto e virgola; un uso corretto di un punto e virgola.

— RubberDuck,

1

Personalmente userei i due punti qui invece di un punto e virgola (anche se legge bene anche con un punto e virgola).

— Marc van Leeuwen,

0

So che è già stata data una risposta, e la risposta accettata è abbastanza buona, ma voglio solo chiarire qualcosa.

Nella grammatica inglese corretta, la linea di fondo è questa: a volte ai nomi propri vengono dati nomi che non iniziano con una lettera maiuscola e, nella maggior parte dei casi, sono altrettanto legati al non essere maiuscoli come i nomi propri "normali" essere capitalizzato. In tali casi - che certamente includerebbe la maggior parte dei nomi di funzioni nelle lingue discendenti in C - non si fa mai uso del maiuscolo, nemmeno all'inizio di una frase. In effetti, è cattiva grammatica inglese e ortografia per farlo. Questo è in realtà una parte dello stesso principio del perché è corretto scrivere la console di gioco "PlayStation" di Sony, ma non "Playstation".

Ci sono altri casi in cui non si suppone che un nome proprio sia maiuscolo per impostazione predefinita, e tuttavia può essere (e dovrebbe essere) quando usato all'inizio di una frase. Il nome della lingua brainfuck ne è un esempio. Le funzioni nelle lingue discendenti in C non lo sono. myFunc()e MyFunc()sono due cose totalmente diverse in linguaggi del genere, e iniziare una frase con la parola "MyFunc ()" farà riferimento solo a quest'ultimo, non al primo. In VB.NET, tuttavia, questa è un'area grigia, poiché queste due funzioni sarebbero la stessa cosa in quella lingua, anche se i nomi delle funzioni manterrebbero anche schemi di capitalizzazione specificati dall'utente, in un modo o nell'altro.

Inoltre, anche se le regole inglesi sono messe in pietra in questo caso, tendono a diventare un po 'confuse su cose come questa come regola. L'inglese non è stato progettato pensando a cose come questa, quindi per altre cose come questa c'è spazio per l'improvvisazione.

— Panzercrisis
fonte