03.08.2003 :: Jaime Irurzun
Poco a poco intento coger la costumbre de documentar en la cabecera todos los archivos de código fuente y las funciones que voy escribiendo. Hasta hace pocos días sólo lo hacía si me acordaba, y tenía unas documentadas y otras no.
Al toparme con códigos fuentes de distintas personas, he visto que cada uno lo hace a su manera. En la cabecera del módulo unos llevan un formato fijo indicando el proyecto, el autor, una descripción, la fecha de la última modificación… etc; otros simplemente encierran en un recuadro de asteriscos una breve descripción y donde caiga escriben su nombre. En las funciones los hay que comentan cada parámetro que recibe y su significado, otros se conforman con una breve descripción de lo que hace la función… y otros no ponen nada.
Para quien no tenga costumbre y la quiera coger, así documento yo cada módulo:
Y así cada función:
comentarios (6) |
El Multiedit de DOS ya tenia una magnifica funcion de documentacion automatica que documentaba y actualizaba esa documentacion, de un aldo, en la cabecera de fichero ponia el prototipado de las funciones y luego en la cabecera de funcion/procedimiento/metodo ponia algo asi como, que no se ve bien por culpa de los espacios, pero en el codigo forma rectangulos perfectos:
/*--¦ Program +------------------------------------------------------------+
¦ Aplicacion : Nominas ¦
¦ Fichero : MAIN.PRG ¦
¦ Autor : Jacinto ¦
¦ Fecha creacion : 04-27-95 ¦
¦ Hora creacion : 07:24:24am ¦
¦ Fichero "Make" : Makefile.Mak ¦
¦ Fichero "Exe" : Main.EXE ¦
¦ Copyright : 1995 by Punt ¦
¦ Telefono Barb. : 342 78 49 ¦
+-------------------------------------------------------------------------*/
/*--¦ Funcion +------------------------------------------------------------+
¦ Descripcion : Configuracion del menu principa ¦
¦ ¦
¦ Autor : Jacinto Diseñada : Jacinto ¦
¦ Fecha creacion : 05-10-95 Fecha rev. : ¦05-20-95 ¦
¦ Hora creacion : 11:51:03pm Hora revi. : ¦11:47:05am ¦
¦ Aplicacion : Nominas Documentada: Eva & Jacinto ¦
+--------------------------------------------------------------------------¦
¦ Funcion : MenuBuild() ¦
¦ Llamada por : Main() ¦
+-------------------------------------------------------------------------*/
// Function/Procedure Prototype Table - Last Update: 20/08/95 @ 02:32:22
// ??????????????????????????????????????????????????????????????????????????
// Return Value Function/Arguments
// ??????????????????? ?????????????????????????????????????????????????????
// function ColoAle... static function ColoAleat()
// Abre( cFile, uIndex function Abre( cFile, uIndex )
// AbreList( aFiles ) function AbreList( aFiles )
// ArraToMemo( aVector function ArraToMemo( aVector )
// Astr( nX ) function Astr( nX )
// Box( nTop , nLeft , function Box( nTop , nLeft , nBottom, nRight, cTitle, ;
// ClaveOk() function ClaveOk()
// CloseList( aFiles ) function CloseList( aFiles )
// DatRange( dFinal... function DatRange( dFinal, dInicio )
// Obj2String( oDato ) function Obj2String( oDato )
// EscribeReg( cDbf... function EscribeReg( cDbf, aCampos )
// ExternEdit( cTex... function ExternEdit( cTexto )
// FiltroSiNo( cX, ... function FiltroSiNo( cX, oGet )
// GetUVar( cTitle,... function GetUVar( cTitle, uVar, bValid, cText, cColor )
// Info( cDbf, lInd... function Info( cDbf, lIndice, lInforme, uLinea )
// String2Obj( oDato ) function String2Obj( oDato )
// LeeRegistro( cDb... function LeeRegistro( cDbf, aCampos )
// MemoToArra( cTex... function MemoToArra( cTexto )
// NAND( bBlock, uV... function NAND( bBlock, uVal1, uVal2 )
// Nada() function Nada()
// NoEmptyField( cF... function NoEmptyField( cField )
¿ Tu eres Jacinto Foix ?
Si es así, cuanto tiempo sin saber nada de ti.
Escribeme por favor.
Saludos,
Hola, Existe un programa en DOS, que documenta
todos tus programas, pniendo un encabezado del PRG
las funciones que hay en el, las funciones a las que llama, las funciones que lo llaman a el, las bases, indices que uso, esta muy bueno, y lo practico es que, si modifico una funcion, ya sea cambiar de nombre o agregar una, y lo documento, el programa lo hace solo.
Hola Alejandro,
¿Y cómo se llama ese programa? Tiene buena pinta.
hermanos,
Acredito que uma coisa muito importante seria colocar as mudanças(change´s) que foram feitas
For Example:
'*----------------------------------------------------------------------------------------------------------
'* Pagina......:
'* Data/Autor..:
'* Descrição...:
'*----------------------------------------------------------------------------------------------------------
'* Objetivo....:
'* Utilização..:
'* Parâmetros..:
'* Retorno.....:
'*----------------------------------------------------------------------------------------------------------
'* Atualizações:
'*----------------------------------------------------------------------------------------------------------
'* Data/Autor..: 01/10/2003 - Marcelo Duarte
'* Descrição...: Reestruturação
'*----------------------------------------------------------------------------------------------------------
ninguno