Un texto que explica la importancia de documentación de software y la metodología que utilizarán para producirla, con ligas a herramientas
Importancia de la documentación de software.
Al decir documentar software, entendemos que es agregar información útil para que nosotros como desarrolladores podamos entender mas facil que es lo que se esta haciendo un código teniendo así una idea mas clara de como esta funcionando el software, explicando por que se hace cada cosa, es importante que como futuros programadores tengamos la iniciativa de realizar documentación ya que como todo, podemos cometer errores los cuales debemos de darle solución en conjunto con personas que no están ligadas con el programador inicial o agregar nuevas necesidades al programa según sea el caso, con una documentación esto es mas sencillo para una persona quien no se vio involucrado desde el principio, que viendo un trabajo que ya se realizó poder iniciar a partir de esto, otra cuestión es que si queremos desarrollar un trabajo en equipo, aqui tambien podemos ver la utilidad de la documentación al poder entender que hizo una persona y otra por lo tanto simplemente todo software que tenga futuro, tendrá que ser modificado para tener éxito.
En resumen, la importancia de la documentación es simple y sencillamente para poder restaurar, reparar, cambiarlo y modificarlo pensando en un desarrollo futuro.
Metodologia en Objective-C
Para empezar creo que es importante decir que documentar es agregar descripciones a todo lo que no es obvio y no debemos reincidir en lo que se esta haciendo repitiendo lo mismo que representa, lo que necesitamos es declarar porque se esta haciendo.
En mi caso utilizaré Doxygen, se comenta muy parecido a javadoc.
Para empezar, debemos documentar primero constructores de lenguaje C, despues los de Objective-C
/**
Describimos la cadena de caracteres
*/
const char* Cadenita = "Carmen, se me perdio";
/**
Describimos una variable
*/
int Eje = 1;
float una, /**< Esto es cuando */
dos, /**< Tenemos multiples */
tres; /**< Variables */
/**
Asi se comenta una estructura de C Alumno
*/
struct Alumno {
/**
Podemos describir asi cada variable en este caso nombre
*/
char nombre[15];
char apellido[15]; /**< asi tambien, apellido */
}
/**
Asi se comenta un define SoyUno
*/
#define SOYUNO 1
/**
Una funcion se documenta asi
@param x decribimos el parametro x
@param y describimos el parametro y
@returns lo que devuelve, en este caso una suma
*/
int suma( int x, int y);
/**
Esta es una clase Carro
*/
@interface Carro : UIKit {
/**
El nombre del modelo del carro
*/
NSString *Nombre;
/**
El numero del modelo
*/
NSUInteger Numero;
}
/**
Muestra el precio de la que se va a pagar a dolares
*/
@property(readonly) NSDecimalNumber *Cambiame;
/**
Inicializa un nuevo Carro Objeto
@param nombre El nombre de modelo
@param numero El numero de modelo
@returns un objeto inicializado
*/
- (id)inicializaConNombre: (NSString *)nombre
ModeloNumero: (NSUInteger)numero;
@end
//Extras
/**
Clase que contiene muchas funciones
@author Roberto Martinez http://roberto-mtz.blogspot.com
*/
@interface Funciones : NSObject {
}
/**
Regresa la multiplicacion de dos numeros
@param x Es una x con un valor entero
@param y Es una y con un valor entero
@returns la multiplicacion
@since version 1.1
@see Nombre-de-la-clase#Metodo-de-la-clase
@see http://www.youtube.com/watch?v=8vHd5Jw3D2I
@exception puede arrogar una excepcion
@deprecated Pensamos que mejor utilizamos la suma
*/
int multipliacion( int x, int y);
Aqui podemos ver las diferentes situaciones que se nos pueden presentar y que tags agregar para que todo sea mas especifico Les dejo ligas de donde pueden encontrar esta información y donde descargar el Doxygen
Documenting Objective-C Part 1
Documenting Objective-C Part 2
Doxygen Latest release
Documentación de código
Espero que mi entrada les sea de utilidad a todos aquellos que documentan en Objective-C
Bien, 5.
ResponderEliminar