documentation - programar - ¿Los programadores deberían poder escribir claramente?
el mejor editor de texto linux (11)
Leí el libro de Richard P. Gabriel "Patterns of Software" ( pdf ) que contiene un ensayo titulado "Writing Broadside" en el que afirma que los programadores deben desarrollar su capacidad para escribir con claridad. Descubrí que sus sugerencias definitivamente han mejorado mi capacidad para escribir especificaciones técnicas y documentos de diseño.
Una de sus sugerencias es desarrollar talleres de escritura en el trabajo. Que esto ayudará a mejorar su capacidad de expresarse claramente al documentar sus diseños.
Ya tenemos un sistema en el que, una vez a la semana, un miembro del equipo da una charla sobre cualquier tema para ayudarnos a mejorar nuestra capacidad para hacer presentaciones.
Así que estoy pensando en sugerir los talleres de escritura también.
¿Alguien tiene talleres de escritura en su lugar de trabajo?
"Un hombre que tiene el conocimiento pero carece de poder para expresarlo claramente no está mejor que si nunca tuvo ninguna idea". - Tucídides
Editar: De lo que estoy hablando aquí es de la capacidad de documentar su código de una manera clara, por ejemplo, especificaciones técnicas y documentos de diseño. No es la escritura del código fuente en sí.
¡Sí! Definitivamente.
Uno de los mayores problemas que veo en el código es la incapacidad de nombrar las cosas con precisión. Esto a menudo puede deberse a la incapacidad de expresar las propias ideas.
Un gran recurso para mejorar las habilidades de escritura es: Los elementos de Style . Es pequeño, sucinto y fácil de leer.
@slashmais: cualquier persona en cualquier tipo de capacidad profesional debe ser capaz de comunicarse claramente, ya sea ingeniero, gerente, probador o lo que sea. Esto no es solo una preferencia personal, creo que esto por el bien de una organización o empresa. No quiere programadores cuya única función es implementar y documentar pobremente el código; desea ingenieros que puedan pensar profundamente sobre el código y comunicar su intención a otros en un medio externo a la lista del código.
Lo que hacemos en mi empresa es una presentación técnica semanal de un ingeniero sobre un tema de su elección. Este es un gran logro para todos: ayuda al ingeniero a perfeccionar sus habilidades de expresión oral y escrita y nos educa sobre lo que están haciendo. También tenemos revisiones de código donde la documentación del código se critica tanto como el código mismo. Esto lleva a un código mucho más fácil de mantener.
No importa si se trata de mensajería instantánea, correo electrónico, documentos escritos o código: mientras menos tiempo tenga para tratar de analizar su comunicación, y cuanto más tiempo pase cumpliendo con las tareas de comunicación, mejor será para mi empresa.
Cita Obligatoria de Dijkstra:
Además de una inclinación matemática, un dominio excepcionalmente bueno de la lengua materna es el activo más importante de un programador competente.
Lo que hacemos es permitir que los compañeros de trabajo hagan una presentación cada semana, principalmente sobre temas técnicos, para que también recibamos capacitación avanzada.
Supongo que esto no solo entrena la capacidad de expresarse, sino que también fortalece el equipo y la comunicación dentro del equipo.
Realmente mejora la productividad si los miembros del equipo saben cómo expresarse, incluso en lo que respecta a cosas pequeñas como la diferencia entre "parámetros" y "argumentos".
Sí, los programadores deben documentar su propio trabajo; ¿construirías una casa a partir de un modelo de una octava escala y confiarías en que los planos no eran necesarios?
Vale la pena leer: Código completo de Steve McConnell, especialmente los capítulos sobre funciones de nombres y documentación de escritura. Si está nombrando y comentando su código de forma adecuada, los documentos se escriben ellos mismos.
mis pensamientos:
R: Lo más importante es que creo que un desarrollador debe poder escribir un código claro, conciso, hermoso y autodocumentado. Esto es mucho más importante que escribir documentos.
B, las pruebas de su unidad también deben ser claras y concisas, y una forma de documentación sobre cómo usar el código.
C. Parte de esto depende. Si son programadores de muy bajo nivel que trabajan en partes pequeñas del código, A + B están de pie. Sin embargo, si son de alto nivel, o trabajan en una gran parte del sistema, o en todo el sistema, entonces sí se vuelve más importante que Saber escribir de forma clara y adecuada, pero hasta cierto punto.
En resumen, creo que es importante, pero no es la medida de cuán bueno es el desarrollo. Qué tan bien se documenta el código en sí es la verdadera medida.
Además, si cada desarrollador pudiera escribir documentos, entonces los escritores técnicos se quedarían sin trabajo.
En cuanto a saber cualquier recurso o qué sugerir, no, nunca lo hice. Nunca he buscado mejorar mis capacidades de escritura.
EDITAR: También debo añadir que parte de esto depende del proceso que use y de los roles y responsabilidades que pueda tener un desarrollador. Obviamente, si se requiere que los desarrolladores escriban parte del manual del usuario, entonces sí, escribir con claridad es MUY importante. Pero esta no suele ser la norma.
EDIT2: Nada de esto pretende decir que un devloper no debe tener NINGUNA habilidad de escritura, sino más bien que la escritura de código es mucho más importante que la escritura de tecnología / doc .
EDIT3: Ahora que se ha aclarado que el OP no quiere ninguna referencia al código de escritura, entonces debo decir que no, en general no es muy importante para un desarrollador poder escribir documentación técnica y documentación de diseño, ya que Cosas mucho más importantes para que un desarrollador sea bueno.
La comunicación es esencial en cualquier profesión, la ingeniería de software y la programación de computadoras no son una excepción. No importa cuán brillante sea su idea si no puede comunicarla efectivamente a sus compañeros, gerentes y clientes. Puede tener tanta influencia con un texto bien escrito como con un código bien escrito.
Un buen ejemplo que estoy seguro es familiar para la mayoría de las personas que leen esto es el famoso libro de K & R. En mi opinión, una de las razones por las que C se convirtió en un lenguaje de programación tan destacado es porque Kernighan y Ritchie produjeron un libro bien escrito. Si hubieran producido un manual que fuera típico del estilo de los manuales de compilación de la época en lugar de un libro de texto fácil de seguir, conciso y competitivo, dudo que C se hubiera vuelto tan dominante como lo fue.
Aquí en Argentina tenemos que comunicarnos con nuestros amigos en los EE. UU. Para hacer nuestro trabajo.
La principal forma de comunicación es el correo electrónico y la mensajería instantánea. No imaginaría lo difícil que es entender muchos correos electrónicos debido a la falta de buena escritura. Y no estoy hablando de cosas técnicas difíciles, sino de cómo expresarse en inglés sencillo.
Entonces sí. Creo que es muy importante.
Los desarrolladores de software se parecen mucho a los profesionales de cualquier otra área o industria que deberían poder expresar sus pensamientos e ideas.
El desarrollo de software es un esfuerzo de equipo y la comunicación es el factor individual más importante que puede causar fallas en el proyecto. Más aún, hoy en día los desarrolladores de proyectos se comunican con las ventas, el marketing, la gente de negocios, los usuarios y otros, y no tienen ni idea del desarrollo de software. Y la capacidad de comunicar ideas y apoyar a otros hacia ellas es una habilidad muy crítica.
No hace falta decir que si Tech Lead presentó un diseño brillante pero no puede comunicar su diseño al resto del equipo, significa que no tiene diseño .
La tarea de programar involucra dos partes principales. El primero es comunicarle a una máquina qué es lo que intentas hacer con tu código. Esa es la parte fácil, el compilador / intérprete / máquina virtual hace la mayor parte del trabajo allí. La parte difícil es comunicar a los otros programadores lo que intenta hacer con su código.
Debido al aspecto humano de la programación, es vital que seas un escritor eficaz para ser un programador eficaz. Hacer que las cosas funcionen no es lo suficientemente bueno, las personas que vienen después deben comprenderlo y trabajar con él también.
Tener buenas habilidades de escritura puede ayudarlo a escribir el código de una manera más natural (aunque hay pit-falls en los lenguajes naturales, por lo tanto, utilícelo según corresponda). También lo ayudará a documentar, comentar y explicar mejor ese código.
Como dijo Blair Conrad, nombrar cosas también es importante y se beneficia enormemente al tener mejores habilidades de escritura. Lo que usted llama cosas tiene un impacto en la forma en que las personas piensan sobre ellas. Si otros programadores pueden descubrir cómo se pensó el código, entonces tienen una mejor oportunidad de usar ese código como se esperaba.
Sí,
Pero escribir claramente no es lo mismo que tener una ortografía y gramática impecables.
Sin importar cuán buena sea la ortografía de alguien, su escritura será difícil de entender si no puede ordenar sus pensamientos de una manera lógica y decidir qué detalles es importante incluir ( y omitir ).
Un breve comentario que va al grano es mucho mejor que un comentario largo con una gramática impecable que no llega al punto.
Si desea pasar a la administración, ser capaz de escribir rápidamente documentos largos con ortografía y gramática perfectas se vuelve mucho más importante.
Recuerda todo lo fácil que es entender lo que quieres decir, no cómo coinciden con tu estilo de escritura.
La gramática sin fallas no siempre es la mejor manera de comunicarse, por ejemplo
"Este es el tipo de inglés con el que no voy a poner".