/*
 * $Id: codestyl.txt 6361 2004-05-28 05:17:36Z alex_degarate $
 */

/* Note los siguientes comentarios que podemos usar en cualquier lugar

   NOTE: Notas 
   TODO: Algo que debera ser agregado aqu
   TOFIX: Algo que necesita ser corregido 
   OBSOLETE: Algo que podra ser removido de aqu
   QUESTION: Yo tuve algunas dudas en este punto pero Yo podra no tener
             una respuesta.
   OPT: Algo es comentado para mejorar la performance

   como un ejemplo: */


Estndar de Codificacin de Harbour
===================================
(basado mayormente en los estndares de codificacin de PHP)


Implementacin de Cdigo
------------------------

[0] Documente su cdigo en los archivos fuentes y en los archivos de texto
    que van a constituir el manual. [tm]

[1] Funciones que reciben punteros a recursos no deberan liberar a stos.
  por ejemplo, la funcin  int mail( char *to, char *from) NO debera
  liberar la memoria a la que apuntan los punteros "to" y "from".
  Excepciones:

  - Las funciones diseadas para liberar aquel recurso.
    por ejemplo, hb_xfree()

  - La funcin que recibe un argumento booleano, que controla cuando la 
    funcin puede liberar sus argumentos (si es cierto - la funcin 
    debe liberar sus argumentos, si es falso - no debe hacerlo).
    
[2] Funciones que estn estrechamente ligadas  integradas con otras 
    funciones dentro del mismo mdulo, y confan en ese comportamiento 
    poco trivial entre una y otra, deberan ser documentadas como tal y 
    declaradas 'static'. Ellas deberan ser evitadas de ser posible.

[3] Use definciones y macros cuando sea posible, as estas constantes 
    tienen nombres significativos y pueden ser fcilmente manipulados.
    Use TRUE  en lugar de 1 (en un contexto booleano)
    Use FALSE en lugar de 0 (en un contexto booleano)
    Use NULL  en lugar de 0 (en un contexto de un puntero)
    Siempre use el prefijo 'HB_' para definiciones de nuevos tipos
    de datos y macros.
    Use  bin el prefijo 'PHB_'  el sufijo '_PTR' para tipos de datos 
    que son punteros.
    
    por ejemplo:
    HB_ITEM
    PHB_ITEM
    HB_ITEM_PTR 

[4] Cuando escriba funciones que traten con cadenas, asegrese de recordar
    que Harbour mantiene la propiedad del tamao de cada cadena, y que 
    esta no debera ser calculada con strlen().  Escriba sus funciones de 
    forma tal que estas tomen ventaja de la propiedad tamao  longitud,
    tanto por eficiencia, como para que sean seguras en el tratamiento 
    de cadenas binarias.
    Funciones que cambien cadenas y obtengan sus nuevas longitudes mientras
    hacen esto, deberan devolver esa nueva longitud, as no tienen que
    recalcularlas con strlen().

[5] NUNCA USE strncat().  Si Ud. est absolutamente seguro de lo que est
    haciendo, chequee este documento de nuevo, y recin entonces considere
    usarlo, y an as trate de evitarlo.

[6] Use assert(). No solamente buenos assert encuentran errores, sino 
    que tambin ayuda con la legibilidad del cdigo fuente. 
     - No use assert para el manejo de errores. Use assert solamente para
       la condicin que debe ser siempre cierta.
     - No use asignaciones en condiciones assert. Si Ud. asigna dentro
       de una condicin assert, Ud. se arriesga a un evasivo error que 
       podra ser muy difcil de encontrar en una contruccion de depuracin
       debido al efecto lateral de la asignacin.
       Llamadas a funciones en condiciones assert tambin pueden causar 
       este problema, si ellos modifican uno de sus argumentos  variables
       globales.

[7] Cuando desee inactivar cdigo comentndolo, utilice una sentencia #if 
    y NO utilice #if 0 solamente.  En su lugar use "<cvs username here>_0"
    Por ejemplo #if FOO_0, donde FOO es su nombre de usuario del CVS.
    Esto permite un seguimiento ms fcil del por qu el cdigo fu anulado 
    al ser comentado, especialmente en libreras empaquetadas.

[8] Use  hb_xgrab()/hb_xalloc(), hb_xfree(), hb_xrealloc(), hb_xsize() 
    para manejar la asignacin de memoria. Estas funciones implementan  
    un mecanismo interno "safety-net" que asegura la des-asignacin de 
    cualquier memoria no liberada al final de la aplicacin.
    Ellas proveen tambin valiosa informacin sobre asignacin y 
    desbordamiento, mientras se ejecutan en modo depuracin (debug mode).


Convencin para los Nombres
---------------------------

[1] Los nombres de funciones para nivel-de-usuario definidas en el cdigo 
    fuente en C deberan ser encerradas dentro de la macro HB_FUNC().
    Ellas deberan estar en maysculas.
    El nombre debera ser prefijado con HB_' si esta funcin es una extensin
    al conjunto de funciones definidas en Clipper.
    Las abreviaturas en el nombre no deberan ser usadas cuando ellas 
    disminuyan la legibilidad  el significado de la funcin.

[2] Los nombres de variables deben ser significativos.  Los nombres de 
    variables de una letra deben ser evitados, excepto para lugares donde 
    la variable no tiene un real significado  tiene un significado trivial 
    (por ej.   for (i=0; i<100; i++) ...).

[3] Los nombres de variables deberan usar la as llamada notacin Hngara.
    Use letras en minsculas y no use el guin inferior '_' (underscore)
    para separar entre palabras.
    
    Bien:
    pMemoryPtr
    
    Mal:
    p_memory_ptr

[4] Variables estticas deben ser prefijadas con 's_'

[5] Variables Globales (variables compartidas entre mdulos) deberan ser
    prefijadas con 'hb_<module_prefix>' por ej. hb_vm_bDebug, hb_gc_pStart
   

Sintaxis e Indentacin
----------------------

[1] Nunca use comentarios estilo C++ (por ej. // comentario).  
    Siempre use comentarios estilo C en su lugar.
    Harbour est escrito en C, y el propsito es compilarlo bajo cualquier
    compilador ANSI-C compatible.  Aunque piense que muchos compiladores 
    aceptan comentarios estilo C++ el cdigo C, Ud. tiene que asegurarse
    que su cdigo pueda compilarse en otros compiladores tambin.

[2] No use el estilo K&R (Kerningham y Ritchie). por supuesto nosotros no
    podemos y no queremos forzar a nadie a usar un estilo que el/ella no 
    use, pero al final, cuando su cdigo vaya dentro de la parte principal
    de Harbour  de uno de sus mdulos estndares, por favor no use el 
    estilo K&R.  Esto se aplica a todo, comenzando con los estilos de  
    indentacin y comentarios hasta la sintaxis de la declaracin de la 
    funcin.

    Vea tambin
    http://www.tuxedo.org/~esr/jargon/html/entry/indent-style.html
    
[3] Sea generoso con los espacios en blanco y las llaves. 
    Siempre es preferible:

    if( cualquier_cosa )
    {
       bar;
    }

    a esto:

    if(cualquier_cosa)bar;
    
    y a esto:
    
    if( cualquier_cosa )
       bar;

    Mantenga una lnea vaca entre la seccin de declaracin de variables y
    las sentencias de un block, as como tambin entre grupos de sentencias 
    de un block.

[4] Cuando indente, use tres espacios (NO use tabs). Es importante mantener
    consistencia en la indentacin as las definiciones, comentarios y
    estructuras de control permanecen correctamente alineados.


Documentacin
-------------

[1] Siempre que le sea posible documente Ud. mismo las funciones que
    desarrolle. 
    Generalmente es difcil entender el cdigo escrito por otra persona,
    ms an cuando involucra algoritmos fuera de lo cmun, atributos
    y variables del sistema  datos que el documentador no dispone.
    Esto es particularmente evidente en funciones de bajo nivel.

[2] Transcurrido un cierto tiempo, se dificulta la tarea de Documentacin
    debido a que es necesario leer y releer el cdigo varias veces (aunque 
    la tarea la haga el propio desarrollador). Esto es evidente cuando no
    se utilizan variables con un nombre adecuado para la tarea que realizan
    (slo se utilizan letras).
    Por eso se pide encarecidamente que NO se dejen funciones  
    procedimientos sin documentar.

[3] Si la funcin  procedimiento que se est tratando de documentar, hace 
    a su vez llamados a funciones no documentadas del sistema y el 
    desarrollador original no est disponible, podra ser muy difcil  tal
    vez imposible de documentar.

[4] Rastrear cuales funciones estn documentadas y cuales no y si estn 
    total  parcialmente documentadas es un malgasto de recursos adicional
    en tiempo y en gente.

[5] Si Ud. es el desarrollador de la funcin, No se preocupe por la 
    narrativa. Es ms importante saber qu hace la funcin qu argumentos
    recibe, para qu sirven y especialmente qu dato/s se devuelven.

[6] Si Ud. es el desarrollador de la funcin, y utiliza variables  
    funciones no documentadas del sistema, por favor expliquelas tanto como 
    sea posible.
    Si utiliza algn algoritmo raro, explique brevemente qu hace y como
    funciona.

[7] Las aclaraciones  explicaciones que ponga en el cuerpo de la funcin
    encirrelas entre el par /* */ por favor no utilice la doble barra //
    para comentarios porque disminuye su portabilidad.

[8] Recuerde... el proceso de documentacin consume mucho tiempo, usualmente
    lleva ms tiempo escribir la documentacin de una funcin que la funcin
    propiamente dicha.


