Formas de documentar proyectos

Namaris #1 Abr '16

Una de las reglas básicas de la programación es documentar el proyecto antes de empezar a escribir la primera linea de código. Independientemente de la envergadura del proyecto, me gustaría crear este hilo para que todos compartiéramos nuestra peculiar forma de plasmar nuestra idea antes de crear cualquier tipo de aplicación.

Esto puede servir a mucha gente que busca en Google como documentar sus proyectos de programación, sobre todo los novatos.

-Para empezar, este es el mío para pequeñas apps que suelo hacer en mi casa, a ver que les parece:

Inputs (Entradas por parte del usuario)
Estructuración de procesos (descripcion de cada proceso como una única aplicacion, por ejemplo; "Sumar/Restar")
Outputs (Resultado generado por la aplicación que muestra en pantalla)
Recursos (lenguaje de programación, IDE, SO...)
Control de versiones

Ejemplo: Calculadora de sumas y restas

Inputs: Usuario introduce un número y selecciona la operación de "sumar o restar"
Estructura: Lectura de datos de entrada > Funcion de la operación a realizar > Almacenar Resultado
Output: Imprimir resultado
Eclipse IDE
Archivo CSV, formato; AñoMesDiaVersion (20160425001)

Zerokkk #2 Abr '16

En mi opinión, lo mejor es documentar de forma muy breve, pero que dé una visión clara y general de qué se va a hacer.

Mi método personal consiste en separar por requerimientos, diseño base y especificación:

Los requerimientos son una lista de cosas que quieres que tu aplicación pueda hacer. Cuanto más específicos sean, mejor. Si el proyecto tiene cierta envergadura, lo correcto es ordenarlos por secciones.
El diseño base son los cimientos: ¿qué tecnología vas a utilizar? ¿Hay que definir algún protocolo propio? ¿Seguiremos algún tipo de criterio para las interfaces gráficas? ¿Qué tipo e intensidad de testeo necesitaremos para cumplir los requisitos? ¿Qué recursos del sistema se utilizarán? ¿Qué base de datos usaremos?
La especificación es la parte en la cual defines la acción a tomar en cada requerimiento. ¿Necesitas algún algoritmo jodido? ¿Hay que tener control sobre las requests/responses? ¿Queremos hacer una interfaz especial? ¿Qué modelo definiremos en la base de datos para manejarlo?

Y poco más. Soy partidario de documentar algunas cosas en el código, pero sin pasarse. Alguna cosa que creas que puede suponer un problema a la hora de releerlo, como el típico algoritmo rarichungo, o una funcionalidad compleja que utilice muchos recursos a la vez y sea volátil. En esos casos es bueno hacer algún tipo de comentario, pero para cosas que un programador normal pueda entender, mejor dejarlas como están.

1 1 respuesta

Namaris #3 Abr '16

#2 Y herramientas? Lo haces todo en un Word o usas algo especial?

2 respuestas

Zerokkk #4 Abr '16

#3 Sí. No considero necesario hacer diagramas UML ni nada por el estilo a menos que tengas que hacer una tochada de proporciones bíblicas.

Pero es mi método personal, no soy arquitecto de software como para darte unas directrices "formales" a la hora de diseñar aplicaciones.

RaCe #5 Abr '16

Documento markdown breve de introducción, explicando setup, stack usado y otras cosas básicas, para dar una visión general del proyecto + un link a una documentación auto-generada en HTML (rdocs, phpdocumentor, lo q sea que uses) de las clases del proyecto.

1

Namaris #6 Abr '16

Interesante:

Namaris #7 Abr '16

Seria de ayuda si alguien se anima a publicar su proyecto completamente documentado en un espacio publico para tener ejemplos en el hilo.

HeXaN #8 Abr '16

Documentación de código:

Si uso C/C++ tiro de Doxygen para generar la documentación. Si uso Python uso los Docstring (PEP 257) con Sphinx. Usar Word, PDF y demás me parece una cutrez enorme (a parte de ser una manera errónea de documentar).

Análisis/diseño:

Si es para proyectos personales, típico diagrama de clases y tablas en una libreta y a pastar. En una empresa ya tendrán a alguien que se encargue de ello.

1 respuesta

Zerokkk #9 Abr '16

#8 Yo lo poco que he desarrollado ha sido siempre freelancing, no he necesitado mucha documentación, de hecho casi todo lo que pueda documentar son proyectos propios. Documentación en código la justa, para proyectos Java utilizo los javadocs y tan ancho, y sólo para partes reutilizables.

cabron #10 Abr '16 Judas

Una de las reglas básicas de la programación es documentar el proyecto antes de empezar a escribir la primera linea de código.

Acabas de bloquear algo así como el 90% de los proyectos que se desarrollan en el mundo real.

6 1 respuesta

Soltrac #11 Abr '16 MV Wizard

#10 90% creo q es un % demasiado bajo xDDD

1

eXtreM3 #12 Abr '16

Documentar un proyecto gordo sin desarrollar ni una línea es estrictamente imposible.

1 respuesta

Camperito #13 Abr '16

Documentar es basicamente encontrar el nombre adecuado para cada variable / metodo. Y tienes mas de la mitad hecho

2

Soltrac #14 Abr '16 MV Wizard

#12 Tengo aquí un proyecto que llevo trabajando en él 6 años. Vendemos alrededor de 100-200 licencias al año.

Si te digo lo que hay documentado....xDDDDD.

Es fallo mío, es jodido para el que entra nuevo y se tiene q enfrentar a él, pero bueno....yo soy un mierda documentando.

Naith #15 Abr '16 Penitente

Tres palabras: Ingeniería del Software

1

Stricken #16 Abr '16

Buena estructura de clases, métodos descriptivos y tests.

1 1 respuesta

DarkSoldier #17 Abr '16

#16 fin del hilo.

N

NoGoonie #18 Abr '16

#3 Markdown.

Fastestwat #19 May '16

http://elegantcode.com/2010/04/25/if-self-documenting-code-is-the-what-unit-tests-are-the-why/

PaCoX #20 May '16 Ant queen

yo lo que hago es ofuscar a tope sin documentar, así puteo al que lee el código luego jejej. Los malware analyst me tienen k odiar.

MTX_Anubis #21 May '16 :psyduck:

Los que dicen que la documentación se hace a base de buenas prácticas, metodos autodescriptivos y tests espero que se refieran a documentación interna de cara al equipo de desarrollo (y aun así, si el proyecto es grande, en algún sitio esté explicada la arquitectura y como van los tiros).

Porque vamos me encantaría veros cuando empezasteis a programar para android o cualquier otra cosa sin un ápice de documentación, solo a base de api y a verlas venir. Seguro que decíais que la documentación es la polla.

Formas de documentar proyectos

Usuarios habituales

Tags