ide - permitir - texto enriquecido outlook 2013
¿Ayudaría el texto enriquecido a comentar el código? (16)
¡Absolutamente no! Simplemente no confío en que nadie merodee en mi código con "caracteres especiales" que, algún día, me pueden dar otra fuente de dolores de cabeza.
Actualización: Jeremy señala que los comentarios, incluido cualquier formato, siempre se eliminarán antes de que el archivo se envíe al compilador. Esto está bien, pero todavía me desagrada visceralmente la idea de poner caracteres de control en mi código.
Un enfoque que funciona es lo que ReSharper hace. Cuando está "viendo" su código, se pondrá en negrita y azul los comentarios que comiencen con " Nota :". Esto es útil porque nadie está jugando con mi formato de texto, solo están usando códigos de colores basados en el contenido.
Entonces otra vez: no cambies mi formato de archivo. Pero resaltar cosas basadas en el contenido está bien.
Siempre me pregunté por qué tengo que escribir comentarios de códigos de texto enriquecido, también conocidos como pseudocódigos en un editor de texto (vamos, negrita, subrayado) y volvemos al IDE (¿integrado?) Para escribir el programa real, sin mencionar asegurarnos estos documentos se quedan cerca del código.
Entonces, la pregunta es: ¿qué pasa si los IDEs permiten comentarios de código de texto enriquecido? ¿Ayudaría a alguien? ¿Tal vez hacer que la oscura imagen sea más clara para entender teniendo en cuenta que puede enfatizar o enfatizar puntos importantes y usar encabezados y subcabeceras?
(Sí, sé que podemos manejar con * punto importante * y ****** HEADER ****** ¡pero pensemos de inmediato por un momento!
Estoy hablando de un editor de código RTF, integrado en IDEs.
En general, la idea de comentar su código es explicar qué acción deben realizar sus rutinas individuales (o los componentes). No debería necesitar marcar esos comentarios con un formato adicional y lo que otros podrían considerar desorden.
Si una sección en particular necesita imágenes, énfasis o de alguna otra manera necesita una explicación más profunda, entonces eso demuestra la necesidad de notas de la versión o documentación de respaldo. La némesis de un desarrollador, lo sé, pero es mejor mantener las cosas ordenadas y de fácil soporte.
Javadoc ha permitido etiquetas HTML y un montón de etiquetas personalizadas (por ejemplo, para vincular a otras clases o métodos) durante la última década.
La estructura que deseo de la documentación no coincide con la estructura del código fuente.
Por ejemplo, una especificación funcional es una lista de características: cada característica se describe en un solo lugar ... pero la implementación de una característica, por ejemplo, como una transacción desde la interfaz de usuario a la base de datos a través del DAL, no está en un solo lugar en el código fuente
Además, diferentes personas quieren diferentes tipos de documentación:
- ¿Cuál es la especificación funcional?
- ¿Cuál es la interfaz de usuario?
- ¿Cuál es el diseño de datos?
- ¿Cuál es el diseño del software?
- ¿Cuál es el proyecto / proceso de desarrollo?
- ¿Cuál es el caso de prueba?
- ¿Cuál es el resultado de la prueba?
Poner documentación en los mismos archivos fuente que el código fuente no ayuda, imo.
Sin embargo, vea también "programación alfabetizada". No sé lo que es o debía ser la "programación alfabetizada", pero parece útil en al menos un caso restringido, que es, cuando estás tratando de escribir sobre software (por ejemplo, escribir un artículo sobre algún software) .
No, porque los usuarios que ven su código sin sus adiciones especiales de IDE pueden no leer los comentarios.
Sin embargo, puedo entender el auto-formateo personalizable para su IDE. Por ejemplo, su IDE podría configurarse para procesar comentarios en Markdown (que utiliza ), que tiene el beneficio de tener un "código" legible.
Si permite que esta idea pase y se vuelva popular, algún día encontrará hojas de cálculo Excel, o videos, incrustados en el código de alguien. No, por favor, ¡deje que el código fuente, al menos el código fuente !, sea texto simple.
puede consultar el formato de phpdoc utilizado, básicamente usa etiquetas para marcar el contenido, pero puede contener enlaces, etc.
El único texto enriquecido que realmente deseo en los comentarios es hipervínculos para hacer referencia a otras piezas de código. Esto es bastante fácil de lograr con comentarios estilo Javadoc, o simplemente con ctags.
Si los comentarios de texto plano no son claros, probablemente necesite una mejor documentación, no un mejor formato de documentación.
El problema que Steve McConell cita para los comentarios formateados complejos es que, dado que son más trabajos para cambiar, es más probable que queden obsoletos.
Uno podría ser capaz de evitar este problema SI un equipo completo adoptara un IDE de edición de texto enriquecido. Pero se embarcaría en una nueva y valiente metodología de creación de códigos, algo que la mayoría de los equipos sabiamente evitan a favor de adaptar las mejores prácticas actuales.
La documentación incrustada real es otra pregunta y no estoy seguro de la mejor manera de lidiar con esto.
Esta es una pregunta interesante, porque aparte de si realmente es una buena idea en este momento , amplía los límites de nuestra forma de trabajar.
Todas las razones para no mezclar el texto enriquecido y el código no abordan la cuestión de si esto ayudaría a alguien, si también hay un lado positivo que compensa las desventajas. Quizás todavía estaríamos usando Gopher si nadie hubiera hecho este tipo de preguntas e inventado la web.
En cuanto a los comentarios del código fuente, algunas características de texto enriquecido serían más útiles que otras:
- los hipervínculos ciertamente serían útiles, ya que la documentación del código frecuentemente necesita referirse a la documentación que vive fuera del código, así como los enlaces a la documentación en otra parte del código para evitar la duplicación.
- las imágenes serían útiles porque hay muchos casos en que la documentación del código más razonable es un diagrama: algunas personas sí usan UML, por ejemplo
- las listas serían útiles; esta lista, por ejemplo, es más fácil de leer en su versión de texto enriquecido (es decir, el HTML) que en la fuente de reducción
- el formato de fuente es menos importante; los caracteres negrita y cursiva son ocasionalmente útiles para enfatizar y el texto es más legible si los fragmentos de código (p. ej., una
variableName) son más fáciles de leer cuando tienen el formato diferente; diferentes colores tienen poco sentido - los encabezados generalmente no serían útiles, porque si un comentario del código es tan largo que necesita encabezados para introducir la estructura, probablemente debería estar fuera del código.
Irónicamente, es más difícil argumentar en contra de los comentarios de texto enriquecido en el código, cuando estás publicando comentarios de texto enriquecido en : tienes que recurrir al argumento de que el texto enriquecido está bien "a veces".
Incluso en breves comentarios aquí, el texto enriquecido resulta útil, y la fuente de reducción sigue siendo sensata cuando no se ve la versión formateada. Entonces, quizás un buen compromiso sería que un IDE renderice los bloques de comentarios Markdown como texto enriquecido, y muestre el origen de Markdown tan pronto como la posición del cursor esté en el bloque de comentarios.
Me gusta la idea. Dado que los comentarios ya son de un solo color, probablemente sea un tanto limitado, no verdadero texto enriquecido, o sería difícil elegir los comentarios del código. Pero si solo permite negrita, subrayado y tal vez el tamaño de la fuente, sería útil para enfatizar que usted sabe que el código es un kludge, o un tipo de comentario de "nunca edite esto".
Sin embargo, no funcionaría hasta que formara parte de un IDE común y ampliamente utilizado.
Preferiría tener solo los elementos enriquecidos de javadoc, como enlaces a clases, encabezados y otros presentados de una manera rica en texas. esto se convertiría de forma transparente a javadoc html. creo que es una buena idea para una ide.
En realidad, lo que realmente ayuda a comentar el código es cuando los idiomas toman los patrones de comentarios más frecuentemente utilizados y los convierten en características del lenguaje:
La palabra clave final puede eliminar este tipo de comentario:
// Don''t extend this class! Ever!
Los métodos abstractos reemplazan esto:
// make sure you implement foo() bar() and baz() in all child classes
Y una buena programación orientada a objetos organizará código para que no necesite grandes encabezados molestos:
// *******************************************
// ***** Input Handling here *****************
// *******************************************
// * This next section has all the functions *
// * dealing with keyboard input. *
// *******************************************
... se convierte ...
class InputHandler {
// This class deals with keyboard input.
}
Eche un vistazo a Visual Studio 2010, tiene una extensión de ejemplo que inserta imágenes en archivos de código.
En los días en que NeXT mantenía su propia rama privada de GCC, permitía las etiquetas RTF en el código fuente. No solo en comentarios, sino en todas partes. Nunca fue una característica muy utilizada, y finalmente se eliminó. Un problema fue que RTF es realmente difícil de leer con un editor de texto plano, por lo que solo funcionó si todos en el equipo usaran un editor compatible con RTF (y herramienta diff).
Creo que conservar algún tipo de formato en los comentarios sería potencialmente útil, pero creo que algo un poco más legible que RTF podría ser una mejor idea. Markdown podría funcionar bastante bien.
Ya es posible poner texto enriquecido en el código de Python: sphinx . Al menos en forma de RST. Y tampoco es realmente necesario usar un IDE para eso (aunque supongo que algo de ayuda de formateo es útil).