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

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

La tua implementazione fread è stata interrotta. fread deve restituire quanti byte sono stati letti.

A seconda di quanto formale è un documento, può adottare lo stesso approccio. In ogni caso, eliminando il problema identificato, è possibile che lo si desideri utilizzare solo per tale motivo.

Nel mondo del testo in chiaro (come notato da molti nei commenti e altre risposte), l'aggiunta di parentesi ai nomi di funzione aiuta un po ', ma poiché abbiamo anche bisogno di fare riferimento alle entità che non prendono parentesi, questo ha solo un valore limitato . In generale, a meno di adottare una convenzione per circondare il testo con caratteri speciali come parentesi e asterischi, nel mondo del testo in chiaro non c'è altra scelta che eliminare il problema ristrutturando la frase.

Se c'è un requisito assoluto per iniziare ogni frase con un cap, allora sostituisci semplicemente fread con "La funzione fread " ovunque inizi una frase.

Se non si dispone di mezzi tipografici per distinguere (come da un'altra risposta), e forse anche se lo si fa, può essere utile indicare che si sta parlando di una funzione usando i parenti:

Your fread() implementation is broken. fread() needs to return how many bytes were read.

Questo aiuta a "spiegare" perché non è in maiuscolo all'inizio della seconda frase, e aiuta anche (nella prima frase) a capire perché il nome proprio (nome di una funzione) non è maiuscolo in maiuscolo o . Dal momento che (come nome proprio) avrebbe dovuto essere probabilmente.

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

Nel complesso, l'uso di Parens aiuta il cervello del lettore a capire perché appaiono strane parole e cosa sono.

Puoi iniziare la frase dalla descrizione:

The function fread[…]

The method fread[…]

The property breadColor […]

Puoi confrontarlo con la matematica incorporata nelle pubblicazioni. Vedrai molto raramente frasi che iniziano con una variabile o altra matematica incorporata.

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)? .

La pagina man di Linux per fread (3) che altri linkano è una grande esempio di quattro soluzioni comuni.

1. Inizia la frase con "La funzione pippo" o "La funzione pippo". "La funzione fread deve tornare ..." .
2. Contrassegna il nome della funzione con caratteri aggiuntivi in base alla convenzione utilizzata dalla comunità del tuo linguaggio di programmazione. Nel caso di C, una coppia vuota di parentesi, quindi "fread () deve restituire ..." .
3. Utilizza la tipografia (grassetto, caratteri a larghezza fissa o corsivo) per evidenziare il nome della funzione, come: " fread deve restituire ..."
4. 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 è pensata per rendere la documentazione leggibile anche quando un interprete di markdown non è disponibile, quindi circondare in ogni modo il nome della propria funzione con una coppia di apici inversi. (Questo è, immagino, una combinazione delle 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, i Lispers potrebbero preferire che il nome della funzione sia nuda, ma capiranno se scrivi una chiamata alla funzione scheletro, come (fread ...) o (fread) . Risciacqua e ripeti per tutte le lingue che documenti.

Risponderò solo all'esempio specifico fornito:

Your fread implementation is broken. fread needs to return how many bytes were read.

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

Your fread implementation is broken; fread needs to return how many bytes were read.

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

Nella corretta grammatica inglese, la linea di fondo è questa: a volte i nomi propri hanno nomi che non iniziano con una maiuscola, e nella maggior parte dei casi, sono tutti attaccati a non essere maiuscolati come "normali" appropriati i nomi devono essere capitalizzati. In questi casi, che includerebbe sicuramente la maggior parte dei nomi di funzione nelle lingue discendenti in C, non devi assolutamente non in maiuscolo il nome, anche all'inizio di una frase. In effetti, è cattiva grammatica e ortografia inglese farlo. Questo è in realtà una parte dello stesso principio del perché è corretto scrivere la console di gioco di Sony "PlayStation", ma non "Playstation".

Ci sono altri casi in cui un nome proprio non dovrebbe essere maiuscolo per impostazione predefinita, e tuttavia può essere (e dovrebbe essere) se usato all'inizio di una frase. Il nome della lingua brainfuck è un esempio di questo. Le funzioni nelle lingue discusse non lo sono. myFunc() e MyFunc() sono due totalmente cose diverse in linguaggi del genere, e l'avvio di una frase con la parola "MyFunc ()" si riferirà solo a quest'ultimo, non al primo. Tuttavia, in VB.NET, questa è un'area grigia, poiché queste due funzioni sarebbero la stessa cosa in quel linguaggio, sebbene i nomi delle funzioni manterrebbero anche schemi di maiuscole specificati dall'utente, su un livello o un altro.

Inoltre, anche se in questo caso le regole inglesi sono impostate in pietra, tendono ad avere una certa confusione attorno a cose come questa di norma. L'inglese non è stato progettato pensando a cose del genere, quindi per altre cose come questa, c'è spazio per l'improvvisazione.