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

42

Ocasionalmente, ao digitar algo relacionado a uma linguagem de programação que diferencia maiúsculas de minúsculas, acabo iniciando uma frase com um nome de função. Agora, as regras do inglês afirmam que a primeira palavra em uma frase precisa ser maiúscula; o nome da função é minúsculo, no entanto. Se você está se perguntando o que eu poderia estar dizendo que resultaria na primeira palavra como um nome de função, veja este exemplo:

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

Entendo que poderia mudar a segunda instância do pread para It, mas quero saber a melhor maneira de lidar com isso, além de reescrever a frase. Devo colocar em maiúscula o nome da função? A única maneira que eu gostaria de ouvir "reescrever a frase" como resposta é se iniciar a frase com um nome de função viola alguma regra em inglês que eu não conheço. Edit: Eu realmente agradeço a todos por essas respostas. Eles mudaram e melhoraram minha visão sobre o assunto. Eu aprendi um pouco com isso. Estou muito surpreso por não ter pensado nessas soluções simples, mas boas.

Eu acho que minha posição em alternar a frase era muito difícil e agora percebo, devido a essas boas respostas, que alterar a frase em geral parece ser a melhor opção para lidar com esses casos, seja adicionando parênteses após a função ou dizendo A função antes da nome da função e, se disponível, usando a formatação para o nome da função.

functions

— user3462295
fonte

1

@gnat Não estou perguntando como nomear algo, estou perguntando como iniciar uma frase com um nome de função.

— User3462295

13

Existe uma convenção relacionada em matemática que deve-se evitar o início de uma frase com um nome ou fórmula de variável. Isso apesar do fato de termos uma convenção tipográfica de que variáveis e fórmulas são renderizadas em itálico para diferenciá-las do texto. Alguém evitaria escrever "Seja x uma potência de 2. x é positivo, então ..." A correção usual é reformular ou adicionar uma palavra de preenchimento: "Agora x é positivo" ou "Temos que x é positivo" ou algo do tipo.

— Nate Eldredge

9

Um identificador de uma linguagem de programação deve ser tratado como uma palavra estrangeira e não deve estar sujeito às mesmas regras do inglês.

— Rufflewind

1

Existem alguns programadores notavelmente ativos no English.SE ( tchrist ... não tanto Eric Lippert ) - mas isso depende do tipo de resposta que você deseja. Estamos escrevendo isso como programadores em um site focado em programadores. Se você estiver mais interessado nas formalidades da redação técnica, nas diretrizes do periódico e na estrutura adequada de frases em inglês, convém reconsiderar seu público-alvo de especialistas.

2

Esta pergunta parece estar fora do tópico, pois é o idioma e o uso do inglês, e temos um site StackExchange inteiro para isso. De fato, há pelo menos quatro perguntas semelhantes lá . Além disso, diferentes respostas podem ser igualmente válidas, dependendo de onde a escrita aparece, etc.

— Caleb

87

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 frase, mas uma entidade especial.

Sua freadimplementação está quebrada. freadprecisa retornar quantos bytes foram lidos.

Dependendo da formalidade de um documento, ele pode adotar a mesma abordagem. De qualquer forma, isso elimina o problema identificado, portanto, você pode usá-lo apenas por esse motivo.

No mundo do texto sem formatação (como observado por vários nos comentários e outras respostas), acrescentar parênteses a nomes de funções ajuda um pouco, mas como também precisamos nos referir a entidades que não usam parênteses, isso tem apenas um 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 sem formatação há pouca opção a não ser contornar o problema reestruturando a frase.

— Reg Editar
fonte

Sim, eu entendo o seu ponto, ele ainda caiu embaraçoso, mas menos embaraçoso. No entanto, entendo que os sentimentos nem sempre estão alinhados com as regras da gramática e da escrita. Não tenho certeza se existe uma maneira melhor de lidar com isso, então aceitarei sua resposta, a menos que alguém encontre algo melhor.

— User3462295

25

Costumo colocar apenas itálico em coisas como essa - você deve sempre manter os termos que diferenciam maiúsculas de minúsculas, independentemente de onde estejam em uma frase, IMO. freadnão é uma palavra; é um símbolo que representa uma entidade. Não está sujeito à gramática.

— Ant P

4

E ... o que você faz se tiver que lidar com texto simples? Como em um pequeno arquivo de ajuda .txt ou em um e-mail em texto sem formatação? Sugiro incluir esse cenário também na sua resposta.

— Ellesedil 02/09

2

@ Ellesedil Nesse caso, usualmente o sufixo com ()ou (...)para indicar que é uma função. Mas isso nem sempre funciona, especialmente quando se lida com variáveis e coisas do tipo. O que faço então é envolver o nome com `(caractere de marca) para indicar seu código.

— Cole Johnson

4

@ Ellesedil Eu comecei a usar a sintaxe de marcação para indicar elementos de código, mesmo em contextos de texto sem formatação, como comentários. É a única vez em que preciso usar um símbolo de bastão ao escrever inglês simples.

— Keen

53

Se houver um requisito absoluto para iniciar cada frase com um limite, basta substituir freadpor "A freadfunção" onde quer que ela comece.

— código x
fonte

21

Se você não possui meios tipográficos para distinguir (como em outra resposta), e talvez até o faça, pode ser útil indicar que você está falando sobre uma função usando parens:

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

Isso ajuda a "explicar" por que ele não é capitalizado no início do segundo período, e também ajuda (na primeira frase) para entender por que o nome próprio (nome de uma função) não é capitalizada não quer . Desde (como um nome próprio), sem dúvida, deveria ter sido.

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

No geral, o uso de parênteses ajuda o cérebro do leitor a entender por que palavras estranhas aparecem e o que são.

— GreenAsJade
fonte

5

O uso de parênteses também ajuda a reduzir a redundância de texto. Em vez de "a função fread", você pode dizer apenas "fread ()". E também é útil se você tiver algum tipo de destaque para enfatizar a diferença entre itens como nomes e funções de variáveis.

— precisa saber é o seguinte

3

Eu acho que parênteses apenas acrescentam mais confusão. fread()poderia ser uma declaração de chamada. Ou pode estar se referindo a uma função sobrecarregada sem parâmetros.

— Kapex

4

@kapep Geralmente nos documentos referentes ao código, func_name()é lida como "uma função pelo nome func_name", independentemente de a função real possuir ou não parâmetros.

— Eric Finn

3

@EricFinn Na minha experiência, geralmente se refere a funções sem parâmetros, mas certamente depende do idioma e de suas convenções. Por exemplo, as diretrizes oficiais para comentários em Java desencorajam o uso de parênteses: "Ao se referir a uma [forma específica de um método], use parênteses e tipos de argumento. [...] No entanto, se se referir a ambas as formas do método, omita entre parênteses. É enganoso incluir parênteses vazios, porque isso implicaria uma forma específica do método " oracle.com/technetwork/java/javase/documentation/…

— kapex

3

Embora adicionar uma pista visual seja certamente uma boa ideia (a melhor é uma fonte dedicada ou outro destaque), concordo com o kapep que acrescentar parênteses vazias é uma escolha realmente problemática, porque em todos os idiomas que conheço f()significa algo diferente f. Por que não envolvem o nome com algum personagem adequado, por exemplo remarcação de estilo `fread` (que é o que eu tendem a fazer em VCS cometer mensagens)? Ou simplesmente (medo). Obviamente, qualquer coisa assim deve ser feita de forma consistente, não apenas para funções no início de uma frase.

— usar o seguinte comando

10

Você pode iniciar a frase a partir da descrição:

A função fread[…]

O método fread[…]

A propriedade breadColor[…]

— David Sergey
fonte

@Zack: Presidente Obama.

— Marc van Leeuwen

@MarcvanLeeuwen Os títulos são um caso especial. (Também "rainha Elizabeth", "senhor Rogers".) Não tenho uma análise adequada da cabeça, mas intuitivamente acho que elas são consideradas parte do nome e não uma tag de categoria.

— zwol

8

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

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

Talvez esta pergunta forneça mais detalhes: Tudo bem começar uma frase com uma letra grega (variável)? .

— Lukas
fonte

3

+1. Em Mathematics Proofs (Chartrand et al., 2000), cujo capítulo 0 é uma verdadeira fonte de bons conselhos para a escrita matemática, a primeira regra em Usar símbolos é "Nunca inicie uma frase com um símbolo". (O exemplo é uma frase que começa com uma equação; os autores sugerem que a prefira "A equação ___".) Embora nem todos os conselhos sobre escrita matemática necessariamente se apliquem à escrita sobre código fonte, acho que isso é um pouco.

— Ruakh

1

Não tenho certeza se concordo com a analogia. Símbolos como $ x $ são transitórios para uma equação, portanto, é estranho consultá-los como se tivessem um significado global. Se um símbolo como $ \ pi $ iniciar uma frase, eu me sentiria à vontade como leitor.

— precisa saber é o seguinte

1

@ djechlin Não tenho certeza de que iniciar uma frase com um símbolo implique que ele tenha um significado global ou que tenha algo a ver com isso.

— Kyle Strand

@KyleStrand, seria bom saber por que você nunca deve iniciar uma frase com um símbolo. "$ \ pi $ é ..." v. "A constante matemática $ \ pi $ é ..." - você escolhe.

— djechlin

1

@ djechlin: Uma razão é que, se a frase anterior termina com matemática, a matemática no início da frase a seguir pode parecer parte da mesma fórmula com um ponto no meio. (Esse é ainda mais um problema com vírgulas.) Outra questão é que, como os nomes das variáveis geralmente são minúsculas, o olho do leitor perde a dica visual de procurar uma letra maiúscula para encontrar o início da próxima frase.

— Nate Eldredge

3

A página de manual do Linux para fread (3) que outros vincularam é um ótimo exemplo de quatro soluções comuns.

Comece sua frase com "A função foo" ou "A função foo". "A função fread precisa retornar ..." .
Marque o nome da função com caracteres extras de acordo com a convenção usada pela comunidade da linguagem de programação. No caso de C, um par de parênteses vazio, então "fread () precisa retornar ..." .
Use tipografia (negrito, caracteres de largura fixa ou itálico) para destacar o nome da função, como: " fread precisa retornar ..."
Nos sistemas utilizados man, se a sua função tiver uma página de manual, consulte o capítulo do manual entre parênteses. Entã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, você não pode confiar na tipografia para destacar o nome da sua função. A sintaxe do Markdown destina-se a tornar a documentação legível mesmo quando um intérprete do markdown não está disponível; portanto, envolva o nome da sua função por um par de backticks. (Acho que é uma combinação das 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 dos métodos de instância com um hash, como #fread . Enquanto isso, Lispers pode preferir que o nome da função fique vazio, mas entenderá se você escrever uma chamada de função esquelética, como (fread ...) ou (fread) . Enxágue e repita para todos os idiomas documentados.

— dcorking
fonte

Eu gosto da sua resposta. Fazer isso faz com que escrever sobre funções pareça melhor.

— user3462295

2

Vou apenas responder pelo exemplo específico dado:

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

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

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

— EdHunter
fonte

3

Não! isso tornaria uma sentença ou emenda de vírgula. Gramática muito ruim. Um ponto e vírgula seria bom.

— Martin McCallion

Portanto, usar vírgula nem sempre funciona; mas por que usar vírgula?

— Reinierpost

Não é uma vírgula. É um ponto e vírgula; um uso adequado de ponto e vírgula.

— RubberDuck 02/09

1

Eu pessoalmente usaria dois pontos aqui, em vez de um ponto e vírgula (embora leia bem com um ponto e vírgula também).

— Marc van Leeuwen

0

Sei que isso já foi respondido e a resposta aceita é muito boa, mas só quero esclarecer uma coisa.

Na gramática inglesa adequada, a linha inferior é a seguinte: Às vezes, nomes próprios recebem nomes que não começam com uma letra maiúscula e, na maioria dos casos, estão tão apegados a não serem capitalizados quanto os nomes próprios "normais" devem sendo capitalizado. Nesses casos - o que certamente incluiria a maioria dos nomes de funções em idiomas descendentes C - você absolutamente não coloca o nome em maiúscula, mesmo no início de uma frase. De fato, é uma má gramática e ortografia em inglês. Na verdade, isso faz parte do mesmo princípio do porquê é correto escrever o console de jogos da Sony "PlayStation", mas não "Playstation".

Há 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 língua brainfuck é um exemplo disso. Funções em idiomas descendentes C não são. myFunc()e MyFunc()existem duas coisas totalmente diferentes em idiomas como esse, e iniciar uma frase com a palavra "MyFunc ()" se referirá apenas ao último, não ao primeiro. No VB.NET, porém, essa é uma área cinzenta, pois essas duas funções seriam a mesma coisa nesse idioma, embora os nomes de funções também retivessem esquemas de capitalização especificados pelo usuário, em algum nível ou outro.

Além disso, embora as regras em inglês sejam fundamentais neste caso, elas tendem a ficar meio nebulosas em relação a coisas como essa em regra. O inglês não foi projetado com coisas assim em mente; portanto, para outras coisas como essa, há espaço para improvisação.

— Panzercrisis
fonte