Duda sobre documentación de código

[frijolerou]

Qué tal gentes!!!!!

Tengo una duda respecto a documentar un código que recurre a la estrategia de divide y vencerás. Voy a utilizar un ejemplo bastante burdo e infantil, pero me sirve para lo que quiero preguntar.

Supongamos que tengo un script para fabricar un teclado de computador, en donde todas las acciones están contenidas en un único método principal:

Código:

function fabricarTeclado(){
    Bloque de codigo para fabricar las teclas;
    Bloque de código para fabricar el armazón;
    Bloque de codigo para fabricar los cables de conexión;
    Bloque de codigo para unir todas las piezas;
}

Si aplico la técnica divide y vencerás podría llegar a esto (y aprovecho de documentar brevemente cada una de las funciones, exepto la principal fabricarTeclado):

Código:

function fabricarTeclado(){
    teclas = fabricarTeclas();
    armazon = fabricarArmazon();
    cables = fabricarCables();
    teclado = armarTeclado(teclas, armazon, cables);
    imprimir teclado;
}

// Rutina: fabricarTeclas()
// Objetivo: Fabricar todas las teclas del teclado
// Devuelve: El grupo de teclas fabricadas
function fabricarTeclas(){
    Bloque de codigo para fabricar teclas;
    return teclas;
}

// Rutina: fabricarArmazon()
// Objetivo: Fabricar el cuerpo base del teclado
// Devuelve: El cuerpo base fabricado
function fabricarArmazon(){
    Bloque de codigo para fabricar armazon;
    return armazon;
}

// Rutina: fabricarCables()
// Objetivo: Fabricar los cables de conexion para el teclado
// Devuelve: El grupo de cables fabricados
function fabricarCables(){
    Bloque de codigo para fabricarlos cables;
    return armazon;
}

// Rutina: armarTeclado()
// Objetivo: Armar el teclado uniendo todas las piezas que se le entregan
// Devuelve: El teclado armado
function armarTeclado(teclas, armazon, cables){
    Bloque de codigo para unir las piezas;
    return teclado;
}

En fin, las acciones del método principal fueron separadas en diversos metodos segun sus caracteristicas. Y cada uno de estos métodos fue documentado entrgeando una breve descripción de qué es lo que hace.

Mi pregunta es: ¿en el caso del método principal -fabricarTeclado()- cómo tendría que describirlo considerando que está compuesto por varias sub-rutinas y que c/u de ellas ya ha sido documentada describiendo lo que hacen?

Perdón si la pregunta es un tanto burra, pero fue el único ejemplo que se me ocurrió

[TolaWare]

Pues tienes que documentarlo de manera de describir en forma general lo que hace el metodo, por ejemplo:

// Rutina: fabricarTeclado()
// Objetivo: Fabricar el teclado en su totalidad.
// Devuelve: Nada

[RootK]

algo importante tambien va a depende (tal vez) del lenguaje, por ejemplo en c# puedes documentar tu código y medianta el VS Net te genera un XML para despues con otro programa generar los archivos .chm y te ahorras crear el manual porque al mismo tiempo que vas creando tus métodos, clases, interfaces, etc, vas documentando, un ejemplo de como yo documento es de la siguiente forma (para el caso de componentes)

/// <summary>
/// Personalize a specific control from database to get settings by module
/// </summary>
/// <param name="moduleID">Module ID to identify current control</param>
/// <returns>A Hashtable</returns>
public static Hashtable mGetModuleSettings(int pnuModuleID) {
Hashtable settings = cBLLSiteSettings.mGetSettings(pnuModuleID);

return settings;
}

ahora que si vas a documentar algun aplicacion compartida lo podrías dejar de la siguiente forma:

/// <summary>
/// Objective: Personalize a specific control from database to get settings by module
/// Author: Eduardo Sánchez Almazán
/// Date Created: 07-2006
/// Company S.A
/// </summary>
/// <param name="moduleID">Module ID to identify current control</param>
/// <returns>A Hashtable</returns>
public static Hashtable mGetModuleSettings(int pnuModuleID) {
Hashtable settings = cBLLSiteSettings.mGetSettings(pnuModuleID);
return settings;
}

como te darás cuenta la documentacion puede variar si es orientado a la creacion de algun componente, a una aplicacion donde van a intervenir varios, etc, no hay una regla donde diga que debe ir de cierto modo solo hay recomendaciones y uno establece sus propios estándares

Salu2

[frijolerou]

Gracias a los dos...

RootK... en realidad mi pregunta iba dirigida más al "qué decir" que al "cómo decirlo" en la función fabricar_teclado() para que no sonara redundante.