¿Es normal / aceptable escribir notas, pensamientos, algoritmos, decisiones durante la codificación y el mantenimiento? [cerrado]

22

Algunas personas tienen este problema que no pueden pensar sin palabras. Y escribir sus pensamientos y decisiones es la forma más efectiva de proceder.

Entonces, ¿es normal y aceptable que escriba mis pensamientos y decisiones en algún archivo Notepad ++ durante la codificación?

A veces debería ser aceptable, por ejemplo, al recrear documentación técnica o razonar sobre algoritmos más complejos, pero a veces puede ser extraño, por ejemplo, cuando estoy considerando opciones de diseño y tratando de hacer un juicio.

El impacto de esta práctica en la productividad no está claro. Por un lado, el razonamiento con palabras internas puede ser más rápido que con las palabras escritas. Del otro lado, los problemas más complejos requieren escritura. Además, si uno está atrapado con más opciones de diseño, la sensación es mejor cuando se escribe la decisión, por lo que aumenta la moral.

Al sr
fuente
55
Tiendo a hacer esto también, y generalmente me arrepiento cuando no lo hago. Es realmente útil tener algo que recordar más tarde para recordar por qué hiciste algo de cierta manera, o poder tomar una decisión más tarde cuando no estás en el codo con visión de túnel. Cuando olvido anotar algo, generalmente olvido por qué y luego paso más tiempo volviendo sobre mis pasos.
PseudoPsyche
21
¿Siento que nos falta parte del contexto? ¿Se hizo esta observación en torno a una queja sobre la eficiencia? A menudo, las críticas vienen con sugerencias de causa raíz que pueden ser relevantes o no.
Jim Rush
99
Los "comentarios y documentación" deben escribirse en el código fuente y conservarse. Sus pensamientos acerca de considerar las opciones de diseño pueden escribirse, pero generalmente no se guardan, eso es algo que rara vez le ayudará más tarde (puede guardar notas sobre los resultados de ese proceso de pensamiento, si no está claro en el código fuente, pero eso no es lo que preguntaste). Si prefiere un formulario electrónico, un lápiz y papel, o si puede hacer todo esto en su cabeza, depende de usted, nadie más, pero puede decirle qué funciona mejor para usted.
Doc Brown
44
... PD: Normalmente prefiero lápiz y papel, o una pizarra blanca para estas cosas, y creo que no sería un mejor programador si intentara hacer todo esto en mi cabeza, todo lo contrario.
Doc Brown
77
¿Por qué no sería aceptable? ¿Aceptable para quién?
Paul D. Waite

Respuestas:

62

No solo es normal, es una buena idea.

Hay una cita famosa

"Dame seis horas para cortar un árbol y pasaré las primeras cuatro afilando el hacha".

Tomarse el tiempo para organizar sus pensamientos y planificar su trabajo antes de codificar es un tiempo bien empleado. Poner esos pensamientos en papel le dará tiempo para reflexionar sobre sus planes, criticarlos y organizarlos de una manera que sería muy difícil si se hiciera solo "en su cabeza".

Dan Pichelman
fuente
8
Es una buena cita, aunque eliminaría la atribución errónea. quoteinvestigator.com/tag/abraham-lincoln
Paul Draper
1
Seguramente una declaración verdadera y una buena cita, pero a mi entender la pregunta tiene un enfoque diferente. Por lo que yo entiendo, el OP no tiene dudas sobre la importancia de planificar de antemano. Él pregunta si es más eficiente escribir estos pensamientos / planificación, o simplemente mantenerlos a todos en su cabeza.
Doc Brown
2
Calcule que una hora de afilado es más que suficiente. Esta tarea debería haberse estimado en 3 horas como máximo, pero la holgura se ha gastado en una preparación excesiva sin sentido. ¿Cuál era la moraleja de nuevo? ;-)
Steve Jessop
26

Sí, esto es perfectamente aceptable y normal.

Documentar su proceso de toma de decisiones a menudo es valioso cuando se revisa el código, para ayudar a determinar por qué el código se escribió de cierta manera.

Estas notas se pueden incluir directamente en el código como comentarios, si son lo suficientemente cortas. Los comentarios extendidos a menudo se mantienen como parte de un documento de diseño técnico externo.

mcknz
fuente
44
Recomiendo encarecidamente no incluir notas acerca de considerar las opciones de diseño y tratar de juzgar como comentarios en el código fuente, estos nunca son "lo suficientemente cortos". Solo los resultados finales de ese proceso de pensamiento, pero eso es bastante diferente de lo que pedía el OP.
Doc Brown
3
A menudo me encuentro en discusiones en torno a "por qué tomamos esta decisión". Es increíblemente útil volver a mis notas diarias del proyecto para proporcionar contexto, incluidas las alternativas que discutimos. Creo que estoy en buena compañía: según The Everything Store, Jeff Bezos hace lo mismo.
kdgregory
8
@DocBrown: a veces es una buena idea incluir razones por las que no usó otros métodos / algoritmos posibles para que un futuro desarrollador no intente reemplazar lo que ha hecho
HorusKol
1
@HorusKol: claro, en algunos casos raros, eso es sentido común trivial. Pero eso es muy diferente de "documentar el proceso de toma de decisiones" .
Doc Brown
1
@DocBrown bien, no creo que nadie quiera páginas de notas en su código fuente. :)
mcknz
20

Es una muy buena idea. Justo hasta que se convierta en una forma de postergar.

La clave es el equilibrio. Me parece que soy más productivo si no me encerro sino que capto las ideas a medida que surgen.

Si estoy moliendo a un nivel bajo y surge una idea de alto nivel, simplemente la apunto y vuelvo a ella más tarde.

Planificar el trabajo es una buena idea, pero a menos que tenga que comunicarse o presentar ante una audiencia, las mejores herramientas son un bolígrafo y una servilleta. Captura la idea. No pierdas el tiempo haciéndolo bonito.

naranja confitada
fuente
Markdown es otra excelente manera de tomar estas notas. Mantiene sus manos en el teclado, por lo que hay una interrupción mínima en el proceso de pensamiento.
RubberDuck
1
Ya sea que disparar a un editor o agarrar un bolígrafo y una servilleta es la mejor alternativa, depende totalmente de sus habilidades personales de escritura táctil y escritura a mano. Para mí, la mejor solución es claramente el editor.
cmaster
9

En cualquier situación profesional, no solo es "normal y aceptable", es obligatorio. El ciclo de desarrollo típico consta de dos fases de documentación antes de que comience cualquier codificación:

  1. Documento de requisitos funcionales: generalmente escrito por analistas de negocios, especificando la funcionalidad que se implementará.

  2. Documento de diseño detallado: que es más o menos de lo que estás hablando, solo que más formal, especificando la descomposición funcional (factorización) del sistema, algoritmos, etc. Algunos de mis (muy) antiguos están en línea, por ejemplo, esto .

Para documentación menos formal, el 110% estoy de acuerdo con los comentarios anteriores sobre los comentarios en línea. Ese es el único camino a seguir; de una forma u otra, todo lo demás eventualmente se pierde. Pero los comentarios en línea ordenados y considerados son una habilidad de codificación separada, desarrollada a través del esfuerzo y la práctica como cualquier otra habilidad. Puedes ver algunas de mis cosas (muy) antiguas en, por ejemplo, esto . Ese estilo puede o no ser atractivo para usted. Primero recomendaría encontrar un código bien comentado con un estilo que le guste y emularlo en su propio código. Después de un tiempo, adáptelo como mejor le parezca.

John Forkosh
fuente
4

Un gran lugar para poner este tipo de información es directamente en el mensaje de confirmación de su sistema de control de versiones (SVN, git, etc.). De esta manera, puede ver los cambios y el razonamiento para ellos en el mismo lugar.

Derek
fuente
1
También los hace buscables. Puede buscar mensajes de confirmación en la línea de comandos git y sourcetree, p. Ej. Si solo usa el bloc de notas, lo más probable es que los archivos nunca se vuelvan a abrir y sean difíciles de buscar sin conocer un bash extenso y escribir un script que busque en todos los lugares relevantes.
HopefulHelpful
Intento hacer esto tanto en mis declaraciones de confirmación como en la solicitud de error o función con enlaces a la confirmación. También hago comentarios en línea con fecha en el código con razones por las que cambié el código. Esto ayuda dramáticamente en nuestra antigua base de código chirriante donde los comentarios son en gran parte desconocidos.
delliottg
No, esto es otra cosa. Los mensajes de confirmación deben describir lo que se hizo, no por qué. El por qué se incluye en los comentarios del código de documentación, la documentación adjunta y la resolución del rastreador de problemas. No puede poner cinco páginas de notas y trabajos de diseño en un mensaje de confirmación, ni debería hacerlo.
ligereza corre con Mónica el
Es genial ponerlo en el sistema de control de versiones. Sin embargo, un lugar mejor es un archivo de texto sin formato. Esos son más fáciles de usar que los mensajes de confirmación.
Thorbjørn Ravn Andersen
2

Además de las otras buenas respuestas, agregaré que a menudo escribo mis pensamientos sobre lo que estoy tratando de hacer.

Ser muy explícito al articular lo que estoy tratando de hacer me ayuda a darme cuenta de presunciones, suposiciones y / o requisitos que no necesariamente cumplen.

Eso luego insinúa alternativas, que luego puedo reflexionar mejor cada vez; que escribir ayudando a salvar mi lugar si pienso en otra cosa.

Tomo notas rápidas para explorar la respiración y la profundidad, por lo que funciona de manera recursiva, ayudándome a elaborar, navegar y evaluar un árbol de soluciones, retroceder, explorar, descubrir, darse cuenta y decidir.

Erik Eidt
fuente
1

Anotar cualquier cosa que pueda ahorrarle tiempo a usted / (nuevos) miembros del equipo es tiempo bien invertido. Solo asegúrate de que sea algo que alguien pueda necesitar más tarde y no pienses demasiado a menos que sea un proyecto real a largo plazo.

Tampoco debería tomar tiempo en absoluto. Si pasa tiempo pensando, puede escribir sus pensamientos 1 a 1 (siempre y cuando sean / puedan ser útiles para alguien).

El verdadero problema podría ser pensar demasiado en lo que escribes. El hecho de que esté escribiendo no significa que deba adherirse a algún formato ya existente o que deba realizar todo el camino para crear una documentación completa.

Si elige entre no escribir nada y simplemente escribir notas no formales en un bloc de notas, simplemente escriba notas no formales.

Con suerte
fuente
1

Usted dice: "Algunas personas tienen este problema que no pueden pensar sin palabras. Y escribir sus pensamientos y decisiones es la forma más efectiva de proceder".

Si escribir sus pensamientos y decisiones es la forma más efectiva de proceder, ¿por qué no sería normal y aceptable proceder de la manera más efectiva? Haces lo que funciona mejor para ti. Puede que no sea lo que funciona mejor para otra persona. En ese caso, no deja que otra persona le diga qué es lo mejor para usted, y no le dice qué es lo mejor para ellos. Todos hacen lo que es mejor para ellos.

gnasher729
fuente
1

Los humanos solo pueden sostener alrededor de siete "cosas" en su cabeza a la vez. Esa es la razón de los números de teléfono de siete dígitos. Para que los programadores trabajen eficientemente, tienen que encontrar algún tipo de sistema para descargar cosas de su memoria y recuperarlas rápidamente más tarde según sea necesario. Tomar notas es una forma obvia y directa, pero todos los que trabajan en algo moderadamente complejo tienen que hacerlo de alguna manera . Cuando empareje el programa con alguien, asegúrese de buscar su método.

Una forma común es el desarrollo impulsado por pruebas. En esta metodología, usted escribe una prueba reprobatoria, escribe el código suficiente para que la prueba reprobatoria pase, luego refactoriza su código para que se vea mejor mientras mantiene aprobadas todas sus pruebas existentes. Esta metodología mantiene todas sus "notas" codificadas dentro de las pruebas. Las personas pueden trabajar muy rápido de esta manera sin que parezcan tomar notas, porque solo se centran en la próxima prueba.

Otra forma común es simplemente escribir sus notas en su código como comentarios de pseudocódigo o stubs, y luego sustituirlo gradualmente por algo real. Así es como suelo escribir algoritmos. Mi primer borrador es solo una función principal con pseudocódigo, luego gradualmente se completa en niveles cada vez más profundos de abstracción.

No se sienta mal por usar cualquier método que funcione para usted, pero trate de notar qué métodos están usando sus colegas "eficientes". Tienen las mismas limitaciones humanas que tú.

Karl Bielefeldt
fuente
1
TDD es un ejercicio para tomar notas? No lo creo.
Robert Harvey