harbour-core/harbour/doc/es/codestyl.txt

/*
 * $Id$
 */

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

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

   como un ejemplo: */


Est ndar de Codificaci¢n de Harbour
===================================
(basado mayormente en los est ndares de codificaci¢n de PHP)


Implementaci¢n de C¢digo
------------------------

[0] Documente su c¢digo 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 deber¡an liberar a ‚stos.
  por ejemplo, la funci¢n  int mail( char *to, char *from) NO deber¡a
  liberar la memoria a la que apuntan los punteros "to" y "from".
  Excepciones:

  - Las funciones dise¤adas para liberar aquel recurso.
    por ejemplo, hb_xfree()

  - La funci¢n que recibe un argumento booleano, que controla cuando la 
    funci¢n puede liberar sus argumentos (si es cierto - la funci¢n 
    debe liberar sus argumentos, si es falso - no debe hacerlo).
    
[2] Funciones que est n estrechamente ligadas ¢ integradas con otras 
    funciones dentro del mismo m¢dulo, y conf¡an en ese comportamiento 
    poco trivial entre una y otra, deber¡an ser documentadas como tal y 
    declaradas 'static'. Ellas deber¡an ser evitadas de ser posible.

[3] Use definciones y macros cuando sea posible, as¡ estas constantes 
    tienen nombres significativos y pueden ser f cilmente 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 ¢ bi‚n 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, aseg£rese de recordar
    que Harbour mantiene la propiedad del tama¤o de cada cadena, y que 
    esta no deber¡a ser calculada con strlen().  Escriba sus funciones de 
    forma tal que estas tomen ventaja de la propiedad tama¤o ¢ 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, deber¡an 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 reci‚n entonces considere
    usarlo, y a£n as¡ trate de evitarlo.

[6] Use assert(). No solamente buenos assert encuentran errores, sino 
    que tambi‚n ayuda con la legibilidad del c¢digo fuente. 
     - No use assert para el manejo de errores. Use assert solamente para
       la condici¢n que debe ser siempre cierta.
     - No use asignaciones en condiciones assert. Si Ud. asigna dentro
       de una condici¢n assert, Ud. se arriesga a un evasivo error que 
       podr¡a ser muy dif¡cil de encontrar en una contruccion de depuraci¢n
       debido al efecto lateral de la asignaci¢n.
       Llamadas a funciones en condiciones assert tambi‚n pueden causar 
       este problema, si ellos modifican uno de sus argumentos ¢ variables
       globales.

[7] Cuando desee inactivar c¢digo coment ndolo, 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 m s f cil del por qu‚ el c¢digo fu‚ anulado 
    al ser comentado, especialmente en librer¡as empaquetadas.

[8] Use  hb_xgrab()/hb_xalloc(), hb_xfree(), hb_xrealloc(), hb_xsize() 
    para manejar la asignaci¢n de memoria. Estas funciones implementan  
    un mecanismo interno "safety-net" que asegura la des-asignaci¢n de 
    cualquier memoria no liberada al final de la aplicaci¢n.
    Ellas proveen tambi‚n valiosa informaci¢n sobre asignaci¢n y 
    desbordamiento, mientras se ejecutan en modo depuraci¢n (debug mode).


Convenci¢n para los Nombres
---------------------------

[1] Los nombres de funciones para nivel-de-usuario definidas en el c¢digo 
    fuente en C deber¡an ser encerradas dentro de la macro HB_FUNC().
    Ellas deber¡an estar en may£sculas.
    El nombre deber¡a ser prefijado con HB_' si esta funci¢n es una extensi¢n
    al conjunto de funciones definidas en Clipper.
    Las abreviaturas en el nombre no deber¡an ser usadas cuando ellas 
    disminuyan la legibilidad ¢ el significado de la funci¢n.

[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 deber¡an usar la as¡ llamada notaci¢n H£ngara.
    Use letras en min£sculas y no use el gui¢n inferior '_' (underscore)
    para separar entre palabras.
    
    Bien:
    pMemoryPtr
    
    Mal:
    p_memory_ptr

[4] Variables est ticas deben ser prefijadas con 's_'

[5] Variables Globales (variables compartidas entre m¢dulos) deber¡an ser
    prefijadas con 'hb_<module_prefix>' por ej. hb_vm_bDebug, hb_gc_pStart
   

Sintaxis e Indentaci¢n
----------------------

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

[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 c¢digo vaya dentro de la parte principal
    de Harbour ¢ de uno de sus m¢dulos est ndares, por favor no use el 
    estilo K&R.  Esto se aplica a todo, comenzando con los estilos de  
    indentaci¢n y comentarios hasta la sintaxis de la declaraci¢n de la 
    funci¢n.

    Vea tambi‚n
    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 l¡nea vac¡a entre la secci¢n de declaraci¢n de variables y
    las sentencias de un block, as¡ como tambi‚n entre grupos de sentencias 
    de un block.

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


Documentaci¢n
-------------

[1] Siempre que le sea posible documente Ud. mismo las funciones que
    desarrolle. 
    Generalmente es dif¡cil entender el c¢digo escrito por otra persona,
    m s a£n cuando involucra algoritmos fuera de lo c¢mun, 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 Documentaci¢n
    debido a que es necesario leer y releer el c¢digo 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
    (s¢lo se utilizan letras).
    Por eso se pide encarecidamente que NO se dejen funciones ¢ 
    procedimientos sin documentar.

[3] Si la funci¢n ¢ 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, podr¡a ser muy dif¡cil ¢ tal
    vez imposible de documentar.

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

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

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

[7] Las aclaraciones ¢ explicaciones que ponga en el cuerpo de la funci¢n
    enci‚rrelas entre el par /* */ por favor no utilice la doble barra //
    para comentarios porque disminuye su portabilidad.

[8] Recuerde... el proceso de documentaci¢n consume mucho tiempo, usualmente
    lleva m s tiempo escribir la documentaci¢n de una funci¢n que la funci¢n
    propiamente dicha.