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

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.

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".

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.

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.

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.

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.

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.

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.

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.

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ú.