En el contexto de un manual técnico, necesito escribir instrucciones que guíen a los usuarios a través de varias manipulaciones estándar. Al proporcionar ejemplos de estas manipulaciones, he escrito una oración corta que contiene ejemplos de "antes" y "después" que aparecen en bloques verticales (potencialmente de varias líneas) propios. Como resultado, no estoy seguro de si la mitad de la oración debe escribirse en mayúscula. Además, se sugirió en ELU SE que sería preferible eliminar los dos puntos que preceden a los bloques de código. He presentado un ejemplo de esto a continuación también.
con mayúsculas
Por lo tanto, el siguiente código:
camera.start_recording('foo.h264', quantization=25)
Debe ser reemplazado con:
camera.start_recording('foo.h264', quality=25)
sin capitalización
Por lo tanto, el siguiente código:
camera.start_recording('foo.h264', quantization=25)
debe ser reemplazado con:
camera.start_recording('foo.h264', quality=25)
Sin mayúsculas ni dos puntos
Por lo tanto, el siguiente código
camera.start_recording('foo.h264', quantization=25)
debe ser reemplazado con
camera.start_recording('foo.h264', quality=25)
Mi instinto sugiere que el segundo o el tercer ejemplo son preferibles, pero me interesaría conocer las reglas de estilo que abordan este tema. De hecho, si hay una mejor manera de estructurar tales ejemplos que evite estos problemas por completo, ¡me interesaría mucho!
¿Debo poner mayúscula "o" entre ejemplos? fue la pregunta más relevante que pude encontrar para esta (y de hecho fue la esquina de SE donde planteé esta consulta por primera vez, antes de conocer a Writers), y tiendo a estar de acuerdo con su razonamiento de que la versión en minúsculas es preferible. Desafortunadamente, la mejor sugerencia en su respuesta (para usar una lista de viñetas de ejemplos) realmente no se presta a bloques de código potencialmente grandes.
En mi opinión, cualquier respuesta parece desordenada. Una "oración" con mayúsculas a la mitad me molesta; también lo hace una línea que comienza sin mayúscula.
Personalmente, reestructuraría todo para evitar el problema por completo:
Actualmente, la línea 57 de camera.py se ve así:
camera.start_recording('foo.h264', quantization=25)En esta línea, el parámetro
quantizationdebe ser reemplazado porquality, dándonos esto:camera.start_recording('foo.h264', quality=25)
Mire la Figura 1 a continuación. Nuestro código actualmente contiene la línea (1); necesitamos reemplazarlo con la línea (2).
(1) camera.start_recording('foo.h264', quantization=25) (2) camera.start_recording('foo.h264', quality=25)Figura 1 : dos versiones de la línea 57 del código en camera.py
(Obviamente, no sé el nombre del archivo de código, los números de línea o el lenguaje de programación. Sustitúyalo cuando sea necesario. "camera.py" se puede reemplazar con el Ejemplo 1 si está tomando esa ruta).
Me gusta la tercera versión, sin dos puntos, porque el corte visual y el formato del código dejan en claro que se trata de una nueva "cláusula" o pensamiento, y que el fragmento de código no es una oración completa gramaticalmente correcta. Dado que continúa una oración en varios descansos, no usaría mayúsculas.
Creo que Watercleave tiene otra buena solución si no puede decidirse por ninguna combinación de puntuación y mayúsculas.
Me acerco al código en el texto de la misma manera que me acerco al diálogo: el código es una cita de otro "hablante", así que lo destaco del texto que lo rodea. Dado que no es un lenguaje hablado, no uso las convenciones para el lenguaje hablado (misma fuente, comillas, etc.), para no causar confusión, sino las convenciones para mostrar el código (fuente monoespaciada, numeración de líneas, comillas en bloque, etc.) .), pero lo integro sintácticamente de la misma manera, por ejemplo usando dos puntos y continuando oraciones con letras minúsculas.
Por lo tanto, en mi opinión, su segundo ejemplo es el mejor.
Ejemplo:
Cuando Maude, de cinco años, dijo: "No estoy interesada en montar a caballo", lo que en realidad quiso decir fue: "Tengo miedo de los caballos".
Similarmente:
Por lo tanto, el siguiente código:
camera.start_recording('foo.h264', quantization=25), debe ser reemplazado por:camera.start_recording('foo.h264', quality=25).
Por supuesto, no debe poner comas dentro de las comillas del código, ya que las reglas en inglés lo exigen para el diálogo ("riding"). Cuando coloca los fragmentos de código en líneas separadas para una mejor legibilidad, la sintaxis, las mayúsculas y la puntuación siguen siendo las mismas.
Una buena práctica es imprimir todo el guión en un apéndice, y en todo el texto usar los mismos números de línea que en el guión adjunto. A continuación, puede hacer referencia al código por números de línea:
En la línea 21,
quantizationdebe ser reemplazado porquality:
21 camera.start_recording('foo.h264', quality=25)
Haz lo más simple que funcione, que en este caso es el ejemplo 3. Las reglas de la estructura de oraciones realmente no cubren este tipo de cosas. Ese es un defecto de las reglas de estructura de las oraciones, no de los ejemplos mismos.
Recuerda que la primera regla es la claridad. Existen reglas gramaticales y guías de estilo para codificar las prácticas que suelen producir el resultado más claro y menos ambiguo. Son una buena guía la mayor parte del tiempo. Pero estas reglas son sirvientes de la claridad, no su amo, y en algunos casos la claridad exigirá algo que estas reglas no pueden explicar.
Hacer algo más enrevesado o complejo para mantenerse fiel a una regla gramatical o una guía de estilo es poner el caballo delante del carro. Como dijo George Orwell: "Rompe cualquiera de estas reglas antes que decir algo completamente bárbaro".
De vez en cuando tengo que documentar el uso del código y prefiero una estructura clara, así que simplemente diría:
El siguiente código camera.start...
debe ser reemplazado con: camera.start_...
A los programadores no les importarán tus elecciones gramaticales, solo necesitarán saber qué código usar. Sólo mis dos centavos valen la pena. Gracias
david jones
david jones
hendidura de agua
usuario