Comenzando una oración con un nombre de función? [cerrado]


42

Ocasionalmente, mientras escribo algo relacionado con un lenguaje de programación que distingue entre mayúsculas y minúsculas, termino comenzando una oración con el nombre de una función. Ahora, las reglas del inglés establecen que la primera palabra de una oración debe escribirse en mayúscula; sin embargo, el nombre de la función es minúscula. Si se pregunta qué podría estar diciendo que resultaría en que la primera palabra sea un nombre de función, tome este ejemplo:

Su implementación de fread está rota. fread necesita devolver cuántos bytes se leyeron.

Entiendo que podría cambiar la segunda instancia de fread a It, pero quiero saber la mejor manera de manejar esto que no sea simplemente reescribir la oración. ¿Debo poner en mayúscula el nombre de la función? La única forma en que me gustaría escuchar "reescribir la oración" como respuesta es si comenzar la oración con un nombre de función viola alguna regla en inglés de la que no estoy al tanto. Editar: Realmente agradezco a todos por estas respuestas. Han cambiado y mejorado mi visión del problema. He aprendido bastante de esto. Estoy muy sorprendido de no haber pensado en estas soluciones simples pero buenas.

Creo que mi postura sobre la alternancia de la oración fue demasiado difícil y ahora, debido a estas buenas respuestas, me doy cuenta de que alterar la oración en general parece ser la mejor opción para tratar estos casos, ya sea agregando paréntesis después de la función o diciendo La función antes de la oración. nombre de la función y, si está disponible, utilizando el formato para el nombre de la función.


1
@gnat No estoy preguntando cómo nombrar algo, estoy preguntando cómo comenzar una oración con un nombre de función.
user3462295

13
Hay una convención relacionada en matemáticas que se debe evitar comenzar una oración con un nombre o fórmula variable. Esto a pesar del hecho de que tenemos una convención tipográfica de que las variables y las fórmulas se representan en cursiva para diferenciarlas del texto. Uno evitaría escribir "Sea x una potencia de 2. x es positivo, entonces ..." La solución habitual es reformular o agregar alguna palabra de relleno: "Ahora x es positivo" o "Tenemos que x es positivo" o algo por el estilo.
Nate Eldredge

99
Un identificador de un lenguaje de programación debe tratarse como una palabra extranjera y no debe estar sujeto a las mismas reglas del inglés.
Rufflewind

1
Hay algunos programadores notablemente activos en inglés. SE ( tchrist ... no tanto Eric Lippert ), pero depende del tipo de respuesta que desee. Estamos escribiendo esto como programadores en un sitio enfocado en programadores. Si está más interesado en las formalidades de la escritura técnica, las pautas de la revista y la estructura adecuada de las oraciones en inglés, es posible que desee reconsiderar su audiencia experta objetivo.

2
Esta pregunta parece estar fuera de tema porque es en inglés y uso, y tenemos un sitio completo de StackExchange para eso. De hecho, hay al menos cuatro preguntas similares allí . Además, diferentes respuestas pueden ser igualmente válidas dependiendo de dónde aparezca la escritura, etc.
Caleb

Respuestas:


87

En la tipografía, esto generalmente se maneja usando una representación diferente, ya sea que sea o no el comienzo de una oración, para indicar que lo que golpea el ojo no es solo una palabra en la oración sino una entidad especial.

Su freadimplementación está rota. freadnecesita devolver cuántos bytes se leyeron.

Dependiendo de cuán formal sea un documento, puede adoptar el mismo enfoque. En cualquier caso, esto elimina el problema que identifica, por lo que es posible que desee utilizarlo solo por ese motivo.

En el mundo del texto plano (como lo señalan varios en comentarios y otras respuestas), agregar paréntesis a los nombres de funciones ayuda un poco, pero como también necesitamos referirnos a entidades que no toman paréntesis, esto tiene un valor limitado. En general, a menos que se adopte una convención de rodear el texto con caracteres especiales como corchetes y asteriscos, en el mundo del texto plano no hay más opción que eludir el problema reestructurando la oración.


Sí, entiendo tu punto, todavía se siente incómodo pero menos incómodo. Sin embargo, entiendo que los sentimientos no siempre están en línea con las reglas de gramática y escritura. No estoy seguro de si hay una mejor manera de manejar esto, así que aceptaré su respuesta a menos que a alguien se le ocurra algo mejor.
user3462295

25
A menudo solo escribo en cursiva para cosas como esta: siempre debes mantener la mayúscula de los términos que distinguen entre mayúsculas y minúsculas, independientemente de dónde estén en una oración, OMI. freadno es una palabra Es un símbolo que representa una entidad. No está sujeto a gramática.
Ant P

44
Y ... ¿qué haces si tienes que lidiar con texto plano? ¿Como en un pequeño archivo de ayuda .txt o un correo electrónico de texto sin formato? Sugiero incluir ese escenario también en su respuesta.
Ellesedil

2
@Ellesedil En ese caso, generalmente lo sufijo con ()o (...)para indicar que es una función. Pero eso no siempre funciona, especialmente cuando se trata de variables y demás. Lo que hago es envolver el nombre con `(carácter de marca) para indicar que es código.
Cole Johnson

44
@Ellesedil He usado la sintaxis de marcado para indicar elementos de código, incluso en contextos de texto sin formato como los comentarios. Es la única vez que he necesitado usar un símbolo de retroceso cuando escribo en inglés simple.
Keen

53

Si existe un requisito absoluto para comenzar cada oración con un límite, simplemente reemplácela freadcon "La freadfunción" donde sea que comience una oración.


21

Si no tiene medios tipográficos para distinguir (según otra respuesta), y tal vez incluso si los tiene, puede ser útil indicar que está hablando de una función usando parens:

Su implementación fread () está rota. fread () necesita devolver cuántos bytes se leyeron.

Esto ayuda a "explicar" por qué no se escribe con mayúscula al comienzo de la segunda frase, y también ayuda (en la primera frase) para entender por qué el nombre propio (nombre de una función) no se escribe con mayúscula no sea . Dado que (como un nombre propio) podría decirse que debería haber sido.

("posiblemente" porque podríamos discutir si fread () es un nombre genérico o un nombre propio).

En general, el uso de parens ayuda al cerebro del lector a comprender por qué aparecen palabras extrañas y cuáles son.


55
El uso de parens también ayuda a reducir la redundancia de texto. En lugar de "la función fread" puede decir simplemente "fread ()". Y también es útil si tiene una especie de resaltado para enfatizar la diferencia entre cosas como nombres de variables y funciones.
Paul92

3
Creo que los paréntesis solo agregan más confusión. fread()podría ser una declaración de llamada. O podría estar refiriéndose a una función sobrecargada sin parámetros.
kapex

44
@kapep Generalmente en los documentos que se refieren al código, func_name()se lee como "una función por el nombre func_name", independientemente de si la función en sí misma tiene o no algún parámetro.
Eric Finn

3
@EricFinn En mi experiencia, generalmente se refiere a funciones sin parámetros, pero depende de la lengua y sus convenciones. Por ejemplo, las pautas oficiales de comentarios de Java desalientan el uso de paréntesis: "Al referirse a una [forma específica de un método], use paréntesis y tipos de argumento. [...] Sin embargo, si se refiere a ambas formas del método, omita los paréntesis por completo. Es engañoso incluir paréntesis vacíos, porque eso implicaría una forma particular del método " oracle.com/technetwork/java/javase/documentation/…
kapex

3
Si bien agregar una pista visual es ciertamente una buena idea (lo mejor es una fuente dedicada o resaltar), estoy de acuerdo con Kapep en que agregar parens vacíos es una opción realmente problemática, porque en cada idioma que conozco f()significa algo diferente f. ¿Por qué no rodear el nombre con algún carácter adecuado, por ejemplo, 'fread' estilo markdown (eso es lo que suelo hacer en los mensajes de confirmación de VCS)? O simplemente (fread). Por supuesto, cualquier cosa debe hacerse de manera consistente, no solo para las funciones al comienzo de una oración.
Leftaroundabout

10

Puede comenzar la oración desde la descripción:

La función fread[…]

El método fread[...]

La propiedad breadColor[…]


@Zack: Presidente Obama.
Marc van Leeuwen

@MarcvanLeeuwen Los títulos son un caso especial. (También "Queen Elizabeth", "Mister Rogers".) No tengo un análisis adecuado de la parte superior de mi cabeza, pero intuitivamente creo que se consideran parte del nombre en lugar de una etiqueta de categoría.
zwol

8

Puede comparar esto con las matemáticas en línea en las publicaciones. Muy rara vez verá oraciones que comienzan con una variable u otra matemática en línea.

Por lo tanto, concluyo que debes evitar los nombres de las funciones al comienzo de una oración.

Quizás esta pregunta proporcione más detalles: ¿Está bien comenzar una oración con una letra griega (variable)? .


3
+1. En Mathematical Proofs (Chartrand et al., 2000), cuyo Capítulo 0 es una verdadera fuente de buenos consejos para la escritura matemática, la primera regla bajo Usar símbolos es "Nunca comience una oración con un símbolo". (El ejemplo es una oración que comienza con una ecuación; los autores sugieren ponerle el prefacio con "La ecuación ___".) Aunque no todos los consejos de escritura matemática se aplican necesariamente a la escritura sobre el código fuente, creo que esto es un poco cierto.
ruakh

1
No estoy seguro de estar de acuerdo con la analogía. Símbolos como $ x $ son transitorios a una ecuación, por lo que es extraño referirse a ellos como si tuvieran un significado global. Si un símbolo como $ \ pi $ comienza una oración, me sentiría cómodo como lector.
djechlin

1
@djechlin No estoy seguro de que comenzar una oración con un símbolo implique que tenga un significado global, o que de hecho tenga algo que ver con eso.
Kyle Strand

@KyleStrand, sería bueno saber por qué nunca debes comenzar una oración con un símbolo. "$ \ pi $ es ..." v. "La constante matemática $ \ pi $ es ..." - usted elige.
djechlin

1
@djechlin: Una razón es que si la oración anterior termina con matemáticas, las matemáticas al comienzo de la siguiente oración pueden verse como parte de la misma fórmula con un punto en el medio. (Esto es aún más un problema con las comas). Otro problema es que, dado que los nombres de las variables son generalmente minúsculas, el ojo del lector pierde la señal visual de buscar una letra mayúscula para encontrar el comienzo de la siguiente oración.
Nate Eldredge

3

La página de manual de Linux para fread (3) que otros vincularon es un gran ejemplo de cuatro soluciones comunes.

  1. Comience su oración con "La función foo" o "La función foo". "La función fread necesita regresar ..." .
  2. Marque el nombre de la función con caracteres adicionales de acuerdo con la convención utilizada por su comunidad de lenguaje de programación. En el caso de C, un par de paréntesis vacío, por lo que "fread () necesita regresar ..." .
  3. Utilice la tipografía (negrita, caracteres de ancho fijo o cursiva) para resaltar el nombre de la función, como: " fread necesita regresar ..."
  4. En los sistemas que usan man, si su función tiene una página de manual, consulte el capítulo del manual entre paréntesis. Entonces "fread (3) necesita regresar ..."

Los piratas informáticos reconocerán los cuatro enfoques al instante, y usted debería poder elegir uno que coincida con el estilo de su casa o su voz personal.

Como dijiste, no puedes confiar en la tipografía para resaltar el nombre de tu función. La sintaxis de Markdown está pensada para hacer que la documentación sea legible incluso cuando un intérprete de markdown no está disponible, por lo tanto, rodee el nombre de su función con un par de teclas de retroceso. (Esta es, supongo, una combinación de las opciones 2 y 3.)

La opción 2 varía según el lenguaje de programación. Por ejemplo, Ruby y Smalltalk documentos a menudo preceden a los nombres de métodos de instancias con un hash, como #fread . Mientras tanto, Lispers puede preferir que el nombre de la función sea simple, pero lo entenderá si escribe una llamada de función esqueleto, como (fread ...) o (fread) . Enjuague y repita para todos los idiomas que documente.


Me gusta tu respuesta. Hacer esto hace que escribir sobre funciones se vea mejor.
user3462295

2

Solo voy a responder por el ejemplo específico dado:

Su implementación de fread está rota. fread necesita devolver cuántos bytes se leyeron.

Simplemente reemplace el primer punto final (punto) con un punto y coma:

Su implementación de fread está rota; fread necesita devolver cuántos bytes se leyeron.


3
¡No! eso lo convertiría en una oración continua o un empalme de coma. Muy mala gramática. Un punto y coma estaría bien.
Martin McCallion

Entonces, usar una coma no siempre funciona; pero ¿por qué usar una coma?
reinierpost

No es una coma. Es un punto y coma; un uso adecuado de un punto y coma en eso.
RubberDuck

1
Yo personalmente usaría dos puntos aquí en lugar de un punto y coma (aunque también se lee bien con un punto y coma).
Marc van Leeuwen

0

Sé que esto ya ha sido respondido, y la respuesta aceptada es bastante buena, pero solo quiero aclarar algo.

En la gramática inglesa adecuada, la conclusión es la siguiente: a veces los nombres propios reciben nombres que no comienzan con una letra mayúscula, y en la mayoría de los casos, están tan unidos a no estar en mayúscula como a los nombres propios "normales". siendo capitalizado. En tales casos, que sin duda incluiría la mayoría de los nombres de funciones en lenguajes descendientes en C , no se escribe con mayúscula el nombre, ni siquiera al comienzo de una oración. De hecho, es una mala gramática y ortografía inglesa hacerlo. Esto es en realidad parte del mismo principio de por qué es correcto deletrear la consola de juegos de Sony "PlayStation", pero no "Playstation".

Hay otros casos en los que no se supone que un nombre propio esté en mayúscula por defecto, y sin embargo puede ser (y debería ser) cuando se usa al comienzo de una oración. El nombre del idioma brainfuck es un ejemplo de esto. Las funciones en lenguajes descendientes en C no lo son. myFunc()y MyFunc()son dos cosas totalmente diferentes en idiomas como ese, y comenzar una oración con la palabra "MyFunc ()" solo se referirá a lo último, no a lo primero. Sin embargo, en VB.NET, esta es un área gris, ya que estas dos funciones serían lo mismo en ese idioma, aunque los nombres de las funciones también retendrían los esquemas de capitalización especificados por el usuario, en algún nivel u otro.

Además, a pesar de que las reglas inglesas se establecen en piedra en este caso, por lo general tienden a ser un poco confusas en torno a cosas como esta. El inglés no fue diseñado pensando en cosas como esta, por lo que para otras cosas como esta, hay espacio para la improvisación.

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.