Barrapunto

Leo la noticia y no lo entiendo,si me dan los fuentes y los puedo compilar sin ninguna libreria precompilada, que ingenieria inversa tengo que hacer, si ya tengo el algoritmo en codigo (http://www.vorbis.com/download_unix.psp) y si ademas me dan las especificaciones en texto explicaditas en un tocho lo entiendo aun menos (http://xiph.org/ogg/vorbis/docs.html) me lo explique ??

Bueno, hay quien documenta mucho y programa poco. Particularmente ambos son problemas pero si me dan a elegir me quedo con los que documentan poco y programan mucho... :)

Un programa indocumentado es como un libro que no sabes dónde está.

Yo, por ejemplo, las estoy pasando canutas para imprimir en blanco y negro ficheros ps con lp por falta de documentación de este comando que, aunque creo que es posible imprimir en blanco y negro, no encuentro por ningún lado documentación para hacer algo tan trivial.
Yo creo que lo mejor es un equilibrio, pero que estaría muy bien que sepamos aprovechar al máximo los programas que ya existen, pues si un programa tiene muchas aplicaciones pero están ocultas y nadie las conoce es como si no las tuviera.

Un programa con MUCHO código y POCA documentación es una bomba de relojería.

---

Yo prefiero mucha documentación y menos código, al menos el poco código me servirá para algo.

Ejemplo 1: Un compañero se va a trabajar a Alemania en redes neuronales, para ello se basa en código desarrollado por sólo programador, el código no tiene comentarios, los nombres de las variables están escritos en alemán e inglés (50-50), cada vez que tiene que usar una función del api tiene que ir a hablar con el desarrollador, este debe mirarse el código y recordar cómo funcionaba, si ese tío desaparece el código se tira (o te pasas un año para enterarte como funciona).

Ejemplo 2: Quiero usar el stack Bluetooth de linux (BlueZ), no hay documentación (sólo como se instala, nada de programar), me tengo que imprimir todo el código en C y analizarlo, cuando con un simple listado con las funciones y los parámetros comentados tendría todo solucionado.

como programador me las he tenido que ver con codigo de otras personas y he sufrido en muchas ocasiones esa sensacion de "antes lo escribo de cero que entiendo como coño lo hace". Tambien he sentido la sensacion de agradecimiento que te llega cuando alguien llega un poquito mas lejos que simplemente comentar el codigo, por ejemplo, no viene nada mal en un codigo escrito por varias personas que las partes que uno modifica esten rodeadas por su nick:

//Tei - Aqui activamos el modo R-X
LOCK();
  gi.CallMode(TGL_SHARED_R_X);
UNLOCK();
//Tei

Solamente esto ya es una ventaja enorme a la hora de entender un texto. Una forma de llevar esto mas lejos y mas practico es hacer lo siguiente:

#if MODERX //Tei activa aqui el modo RX
LOCK();
  gi.CallMode(TGL_SHARED_R_X);
UNLOCK();
#else
  // Codigo seguro si no hay RX
WAIT();
#endif

Con lo que, joder, es bastante facil activar/desactivar una funcionalidad determinada.

Como diria un santon por ahi "se codifica, se documenta, a la vez". Programar y documentar un programa es la misma cosa... pero hay formas de hacerlo MAL. En mi opinion uno deberia programarse las funcionalidades, asignandoles un identificador, y hacerlas opcionales segun la tecnica que he puesto aqui u otra. Tambien deberia utilizar alguna tecnologia para mantener en sincronia documentacion y codigo, o bien docu-codigo. Creo que algunas personas utilizan algo llamado Doxygen.. a mi esto no me gusta, por eso tiendo mas a escribir un Documento que se puede compilar y es el programa, y aparte llevar una wiki para documentacion orientada al usuario ( la barrera energetica de gestion de una wiki es la mas baja conocida).

Si conocen alguna manera de currar *mas* de la forma *mas* vaga todabia, me avisan.

Por cierto:
Creo que el buen codigo fuente deberia ser facil de leer, y aunque se puede sacrificar la legibilidad para alcanzar la maxima velocidad, yo estoy por sacrificar la velocidad en beneficio de un codigo mas legible incluso en los ambientes donde la velocidad es lo mas importante. Uno pierde el control de un programa cuando se hace ilegible, y finalmente el codigo fuente/lenguaje que gana es el "mejor ciudadano"(mas legible).

IMHO.

¿Alguno conocía el Literate Programming? No digo que sea la solución para los plazos apurados de las empresas de desarrollo de SW, pero para código libre (en especial en entornos académicos) me parece la mejor solución posible.

Ya había leído algo sobre 'Literate Programming' en alguna revista, me parece una MUY buena idea, en java se utiliza el Javadoc que permite extraer documentación del código (utilizas comentarios 'especiales') generando páginas html, pdf, etc. Con esto es con lo que han documentado el API, es simple y funciona muy bien. Personalmente obligaría a utilizarlo para que el programa pudiese compilar, a ver si así hacemos que el software sea más ciencia/ingeniería de una vez.

  Aqui encontrareis la clave: http://mindprod.com/unmain.html

  No tiene desperdicio!

Las especificaciones no están completas como dice el artículo. De ahí la necesidad de hacer ingeniería inversa al código para ver _que_ hace. De todos modos lo explican muy bién aquí

Leer cierto tipo de código fuente puede ser peor que la ingerniería inversa, como ya han comentado por ahí. Lo digo por propia experiencia.

Ese es el título de un libro de Wirth, si no es la biblia de la programación, al menos es una edición de bolsillo.

Es costoso, cuando no imposible, deducir la estructura de los datos a partir de un programa y un algorítmo.¿Cuántas veces has leído un artículo que te explica lo que hace un programa, a pesar de tener el código al lado?

supón que ves este código fuente:

if (estructura.dist>0) then begin
    distancia:=estructura.velo cidad*estructura.tiempo
    estructura.dist:=-1;
end;

Aparentemente la estructura guarda una velocidad y tiempo que se usa para calcular una distancia. ¿Pero puedes decirme que pinta estructura.dist?. Además ¿por qué ha de ser mayor que cero y no mayor o igual?. O quizá debía ser siempre mayor o igual y es un bug, por culpa del cual falla un 2% de las veces.

Que han preferido no divulgar la información para mantener el control.

No es creible que un proyecto que maneja un formato complejo, se esté haciendo sin tenerlo escrito de alguna manera. A nivel interno tienen que estar manejando documentación, más clara o menos, esa documentación es la que piden que ponga a disposición pública.

De hecho si lo hicieran, otros que no la vieron clara reescribirían partes para hacer más clara

Estás intentando deducir que intentaban implementar a partir de una implementación concreta

De todas maneras, o eres un genio o has leído pocos porgramas escritos por otros, incluso escritos por ti mismo al cabo de unos meses.

Suele ser bastante difícil, incluso si están bien comentados, cosa que no es habitual

lo que de verdad es importante es la documentación de diseño, diagramas, etc.

Hombre, para hacer dibujitos te puedes ir a bellas artes... y conste que yo normalmente siempre hago un diseño en UML (o algo parecido...) sobre papel... lamentablemente se suele quedar sobre el papel... pero de ahí a decir que lo importante es el papel...

La verdad, sé programar en C

¡Buf! ¡¡Entonces no me extraña que necesites urgentemente el diseño con dibujitos!!...

(Bueno, Perl es aún peor para estas cosas ahora que no me oye JJ...)

O será que en algunos proyectos de software libre no hay diseño y sólo son unos cuantos megas de código en el lenguaje X?

Te recomiendo la lectura "La Catedral y el Bazar" de ESR.

Francamente, a mi me da por el culo que algunos proyectos no estén debidamente documentados; por ejemplo, ZOPE me lo dejó como la bandera de Japón, especialmente cuando me compré el Zope Book y ví que había tirado ocho mil pelas a la basura... Pero desde luego, prefiero tener el programa mal documentado, a tener una buena documentación sin programa...

Hombre, para hacer dibujitos te puedes ir a bellas artes... y conste que yo normalmente siempre hago un diseño en UML (o algo parecido...) sobre papel... lamentablemente se suele quedar sobre el papel... pero de ahí a decir que lo importante es el papel...

Pues no sé qué decirte, saber programar no es saberte las N palabras clave de un lenguaje, es saber estructurar el diseño. Teniendo una buena documentación, cualquiera puede reimplementar algo.

¡Buf! ¡¡Entonces no me extraña que necesites urgentemente el diseño con dibujitos!!...

¿Dibujitos? Ufff, los diagramas, casos de uso, especificaciones, etc. son algo más que simples dibujitos.

Te recomiendo la lectura "La Catedral y el Bazar" de ESR.

El desarrollo del bazar no está reñido con el diseño ni la documentación. De hecho, una buena documentación permite que muchos más desarrolladores se unan a un proyecto.

Estás insinuando que por ejemplo, la VM de los núcleos libres se va haciendo a base de machacar código? Creo que estás equivocado, mírate por ejemplo los documentos de Matt Dillon sobre el diseño que tenía pensado para FreeBSD, o los papeles sobre la VM de Rick Van Riel para Linux (e incluso hubo una discusión entre Andrea y él sobre que faltaba documentación, pero Andrea en una posición bastante 31337 dijo que "para eso tienes el código").

Y qué me dices de la documentación de PostgreSQL, con razón es una BDD tan fiable, está todo muy pensado, diseñado, documentado, etc. mientras que MySQL, bueno es otro mundo...

O como alguien ha comentado antes, la pedazo documentación de CUPS, es alucinante. Con eso cualquiera podría implementar cosas basadas en CUPS (mira qué rápido se hizo el soporte de CUPS en KDE o en Gimp-Print).

En cierta manera, el libro de ESR era una crítica al modelo de desarrollo de algunos proyectos de la FSF (por ejemplo el GCC, hasta que apareció el fork de EGCS y éste a su vez, se convirtió en el GCC oficial, con un modelo más abierto)

Nadie se empolla el código y no por falta de conocimientos, sino porque es absurdo (si alguien te dice lo contrario, es que o bien miente o bien no ha leído código "grande"). El código te puede representar muy poco tiempo si te has encargado del diseño y la documentación, y a la larga se agradece (además, ayuda a crear código bastante limpio y fácilmente mantenible). Y si algún día decides abandonar un proyecto y más tarde alguien quiere continuarlo, la documentación es el mapa que le das a esa persona para que continue el programa. Por culpa de proyectos mal documentados, se crean muchos proyectos desde 0, cuando se podrían haber continuado y mejorado.

La verdad, sé programar en C

¡Buf! ¡¡Entonces no me extraña que necesites urgentemente el diseño con dibujitos!!...

Bueno, mi proyecto de fin de carrera está en C, y todavía no he hecho ni un sólo dibujo.

Pues claro que es muy fácil criticar. Por eso se critica lo que está mal, sea libre o no. Eso de "en el soft libre no valen las críticas" no te lo crees ni tú. Ni que por picar código libre la gente fuese santa o dejase de hacer chapuzas.

En realidad, el Literate Programming es lo contrario de lo que hace Javadoc. 8)

En Java, pones comentarios esparcidos entre el código, y la herramienta los extrae para generar la documentación.

En LP, pones código esparcido entre la documentación! La herramienta se encarga de extraerlo y reordenarlo para que se pueda compilar.