Começando uma sentença com um nome de função? [fechadas]

Na tipografia, isso geralmente é tratado usando uma renderização diferente, seja ou não o início de uma frase, para indicar que o que está chamando a atenção não é apenas uma palavra na sentença, mas uma entidade especial.

Sua implementação fread está quebrada. fread precisa retornar quantos bytes foram lidos.

Dependendo de quão formal é um documento, ele pode adotar a mesma abordagem. Em qualquer caso, isso elimina o problema que você identifica, então você pode querer usá-lo apenas por esse motivo.

No mundo do texto simples (como observado por vários em comentários e outras respostas), acrescentar parênteses a nomes de função ajuda um pouco, mas como também precisamos nos referir a entidades que não usam parênteses, isso tem valor limitado . Em geral, além de adotar uma convenção de cercar o texto com caracteres especiais, como colchetes e asteriscos, no mundo do texto plano, não há outra alternativa senão contornar a questão reestruturando a frase.

Se houver um requisito absoluto para iniciar cada frase com um limite, simplesmente substitua fread por "A função fread " sempre que iniciar uma frase.

Se você não tem meios tipográficos para distinguir (como por outra resposta), e talvez até mesmo se fizer isso, pode ser útil indicar que você está falando sobre uma função usando parens:

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

Isso ajuda a "explicar" por que não é capitalizado no início da segunda sentença, e também ajuda (na primeira sentença) a entender por que o nome próprio (nome de uma função) não está em maiúsculas ou . Desde (como um nome próprio), sem dúvida, deveria ter sido.

("discutivelmente" porque poderíamos argumentar se fread () é um substantivo genérico ou um nome próprio).

Você pode começar a sentença a partir da descrição:

The function fread[…]

The method fread[…]

The property breadColor […]

Você pode comparar isso com a matemática em linha nas publicações. Você raramente verá sentenças começando com uma variável ou outra matemática em linha.

Assim, concluo que você deve evitar nomes de funções no início de uma frase.

Talvez essa pergunta forneça mais detalhes: .

A página de manual do Linux para o fread (3) que outras pessoas vinculadas é uma ótima exemplo de quatro soluções comuns.

1. Comece sua frase com "A função foo" ou "A função foo". "A função fread precisa retornar ..." .
2. Marque o nome da função com caracteres extras de acordo com a convenção usada pela sua comunidade de linguagens de programação. No caso de C, um par vazio de parênteses, então "fread () precisa retornar ..." .
3. Use a tipografia (negrito, caracteres de largura fixa ou itálicos) para destacar o nome da função, pois: " fread precisa retornar ..."
4. Em sistemas que usam man , se sua função tiver uma página man, consulte o capítulo do manual entre parênteses. Então "o fread (3) precisa retornar ..."

Todas as quatro abordagens serão instantaneamente reconhecíveis pelos hackers e você poderá escolher uma que corresponda ao seu estilo de casa ou à sua voz pessoal.

Como você disse, não pode confiar na tipografia para destacar o nome da sua função. A sintaxe do Markdown serve para tornar a documentação legível mesmo quando um interpretador de markdown está indisponível, portanto, por todos os meios, coloque o nome da sua função em um par de backticks. (Isto é, eu acho, uma combinação de opções 2 e 3).

A opção 2 varia de acordo com a linguagem de programação. Por exemplo, os documentos Ruby e Smalltalk geralmente precedem os nomes de métodos de instância com um hash, como #fread . Enquanto isso, o Lispers pode preferir que o nome da função seja simples, mas entenderá se você escrever uma chamada de função esquelética, como (fread ...) ou (fread) . Enxágüe e repita para todos os idiomas que você documentar.

Eu só vou responder pelo exemplo específico dado:

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

Basta substituir o primeiro ponto final (ponto) por um ponto e vírgula:

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

Eu sei que isso já foi respondido, e a resposta aceita é muito boa, mas eu só quero esclarecer alguma coisa.

Na gramática inglesa apropriada, a linha inferior é a seguinte: Às vezes nomes próprios recebem nomes que não começam com letra maiúscula e, na maioria dos casos, eles são tão ligados a não serem capitalizados como "normais" propriamente ditos. substantivos estão sendo capitalizados. Nesses casos - o que certamente incluiria a maioria dos nomes de funções em idiomas descendentes de C - você absolutamente não capitaliza o nome, mesmo no início de uma frase. Na verdade, é uma gramática e ortografia inglesas ruins. Esta é realmente uma parte do mesmo princípio que explica porque é correto soletrar o console de videogame da Sony "PlayStation", mas não "Playstation".

Existem outros casos em que um nome próprio não deve ser capitalizado por padrão e, no entanto, pode ser (e deve ser) quando usado no início de uma frase. O nome da linguagem brainfuck é um exemplo disso. Funções em idiomas descendentes de C não são. myFunc() e MyFunc() são duas totalmente coisas diferentes em linguagens como essa, e iniciar uma frase com a palavra "MyFunc ()" se referirá apenas a esta última, não à primeira. No VB.NET, porém, essa é uma área cinzenta, já que essas duas funções seriam a mesma coisa nessa linguagem, embora os nomes das funções também mantivessem esquemas de capitalização especificados pelo usuário, em algum nível ou outro.

Além disso, mesmo que as regras inglesas sejam precisas, neste caso, elas tendem a ficar confusas em torno de coisas como essa. O inglês não foi projetado com coisas assim em mente, então, para outras coisas como essa, há espaço para improvisação.