\input texinfo
@setfilename gpcs.info
@settitle Estándar de Codificación GNU Pascal
@documentencoding iso-8859-1

@c Copyright (C) 2001-2005 Free Software Foundation, Inc.
@c
@c Authors: Frank Heckenbach <frank@pascal.gnu.de>
@c          Peter Gerwinski <peter@gerwinski.de>
@c          Nicola Girardi <nicola@g-n-u.de>
@c
@c Remember to update this when you save
@set lastupdate 2005-01-01


@direntry
* Estándares de Codificación Pascal: (gpcs).   Estándares de codificación GNU Pascal.
@end direntry

@setchapternewpage odd

@c Put everything in one index (arbitrarily chosen to be the concept index).
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex vr cp

@ifnottex
GNU Pascal Coding Standards

Copyright (C) 2001-2005 Free Software Foundation. Inc

Se concede permiso para copiar, distribuir y/o modificar este
documento bajo los términos de la Licencia de Documentación Libre
GNU, Versión 1.1 o cualquier otra versión  posterior publicada por
la Free Software Foundation; sin ninguna Sección Invariante, sin
Texto de Cubierta Frontal, sin Texto de Cubierta Trasera.

Se incluye una copia de esta licencia en la sección titulada ``Copia
de la Documentación'' en el Manual de GNU Pascal.
@end ifnottex

@titlepage
@title Estándares de Codificación Pascal de GNU
@author Nicola Girardi
@author última actualización @value{lastupdate}
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 2001-2005 Free Software Foundation, Inc.

Se concede permiso para copiar, distribuir y/o modificar este
documento bajo los términos de la Licencia de Documentación Libre
GNU, Versión 1.1 o cualquier otra versión  posterior publicada por
la Free Software Foundation; sin ninguna Sección Invariante, sin
Texto de Cubierta Frontal, sin Texto de Cubierta Trasera.

Se incluye una copia de esta licencia en la sección titulada ``Copia
de la Documentación'' en el Manual de GNU Pascal.
@end titlepage

@ifnottex
@node Top
@top Versión

Última actualización @value{lastupdate}.
@end ifnottex

@menu
* Prefacio::                            Acerca de los Estándares de Codificación de GNU Pascal
* Cuestiones Legales::                  Mantener el ``Software Libre''  Libre
* Advertencias de Diseño::              Diseño General del Programa
* Comportamiento del Programa::         Comportamiento del Programa con Todos los Programas
* Escritura en Pascal::                 Haciendo el Mejor uso de  Pascal
* Documentación::                       Documentación de Programas
* Gestión de Liberaciones::             El Proceso de Liberación
* Glosario::                            Glosario de palabras usadas a través de este texto
* Índice::
@end menu

@node Prefacio
@chapter Acerca de los Estándares de Codificación de GNU Pascal

Los Estándares de Codificación de GNU Pascal fueron diseñados por un grupo de
voluntarios del proyecto GNU Pascal. El objetivo de este documento es extender
los Estandares de Codificación GNU con información específica relativa a la
programación en Pascal. De hecho, la información contenida en el Estándar
de Codificación de GNU en su mayor parte pertenece a programas escritos en
lenguaje C. Por otra parte, también explican muchas de las reglas y
principios que son útiles para escribir programas portables, confiables y
robustos. La mayoría de esos temas generales podrían compartirse con este
documento con sólo unas notas específicas, así que se dan referencias cruzadas
las cuáles le dirigirán a información más extensa contenida en el Estándar de
Codificación GNU.

Esta liberación de los Estándares de Codificación de  GNU Pascal se actualizó
por última vez el @value{lastupdate}.

@cindex dónde obtener GPCS
@cindex descarga de los estándares de codificación

Los Estándares de Codificación de GNU Pascal están disponibles como parte de
las distribución de GPC -- en las distribuciones binarias como ficheros info,
en las distribuciones fuente también como ficheros  Texinfo desde los que
se pueden generar más formatos como HTML, PostScript y PDF. Una versión HTML
está disponible también en la página inicial de GPC, @uref{http://www.gnu-pascal.de}.

@cindex información
@cindex contribuciones a este manual

Correcciones o sugerencias para este documento deberían enviarse a la lista
de correo de Documentación de Compilador de Pascal de GNU, @email{gpc-doc@@gnu.de}. Si
hace una sugerencia, por favor, incluya la palabra sugerida para ella;
nuestro tiempo es limitado. Un diff contextual al fichero Texinfo  ``fuente'' Texinfo
se agradecerá mucho, si es posible. Si no puede proporcionar un diff contextual, por favor
siéntase libre para enviar por correo su sugerencia igualmente.

Esa gente son los tiranos que están imponiendo si estilo de codificación a la comunidad:
Peter Gerwinski @samp{peter(at)gerwinski.de}, Frank
Heckenbach @samp{frank(at)pascal.gnu.de}, Markus Gerwinski
@samp{markus(at)gerwinski.de}, Dominik Freche
@samp{dominik.freche(at)gmx.net}, Nicola Girardi
@samp{nicola(at)g-n-u.de}.

@node Cuestiones Legales
@chapter manteniendo el ``Software Libre'' Libre
@cindex aspectos legales

Este capítulo de los Estándares de Codificación GNU discuten cómo puede asegurarse
de que el software GNU evita dificultades legales, y otras cuestiones relacionadas.
@xref{Propiedad Intelectual, , , estándares}.

@node Advertencias de Diseño
@chapter Diseño General de un Programa
@cindex diseño de programas

Este capítulo trata sobre las cuestiones que debería tener en cuenta cuando diseñe
su programa.

@menu
* Lenguaje del Fuente::         Qué lenguaje usar
* Pascal y C::                  Enlazando a bibliotecas C
* Uso de Extensiones::          Uso de características no estándar
@end menu

@node Lenguaje del Fuente
@section Qué lenguaje usar
@cindex lenguajes de programación

Apoyamos la idea de que una variedad de lengajes de programación es una
cosa buena y que lenguajes diferentes son apropiados para diferentes clases
de tareas. Al contrario que los Estándares de Codificación GNU
(@pxref{Lenguaje del Fuente, , ,estándares}), no le intentamos persuadir para que
utilice C, Pascal o cualquier otro lenguaje para todo.

Si está leyendo esto, ya ha decidido probablemente usar Pascal para algún
proyecto o está considerando usarlo. Esta documentación le sugerirá
 @emph{cómo} dar formato a su código pascal cuando lo haga.

@node Pascal y C
@section Enlazando con bibliotecas C
@cindex Pascal y C
@cindex enlazando con bibliotecas C

Puede enlazar una biblioteca C o un código objeto C a su programa Pascal o
unidad. Por favor vea la descripción en el manual de GPC sobre cómo hacer esto
(@pxref{Otros Lenguajes, , , gpc}).

@cindex encapsulados
En particular, para acceder a bibliotecas C, recomendamos encarecidamente usar
encapsulados C. Esto es una custión de portabilidad. Quizá haya cambios en
versiones diferentes de la biblioteca que puedan afectar directamente a declaraciones
@samp{external} en el código Pascal. Debería actualizar la encapsulación para que
los programas Pascal o unidades funcionen con cualquier versión de la biblioteca que
tenga.

Hay veces cuando se tratan paquetes grandes que no se puede mantener la compatibilidad
fácilmente entre versiones diferentes de los mismos paquetes. En este caso,
puede enlazar directamente a la biblioteca con la que va trabajar, y enlazar un fichero
C suplementario que no contine nada excepto una verificación de la versión. Este es un
ejemplo:

@smallexample
#include <foo.h>
#if FOO_MAJOR != 1 || FOO_MINOR != 2
#error The GPC interface for libfoo was only written for libfoo-1.2.
#error Please get libfoo-1.2 or check for a version of the GPC interface
#error matching your version of libfoo.
#endif
@end smallexample

Nótese el uso de @samp{!=} en vez de  @samp{<} o @samp{>}, para efectuar
una verificación de versión muy estricta. Por favor tenga en mente que esto
es correcto si hay sólo una implementación de una biblioteca, p.e.,  puede
hacer esto con GTK, pero no puede hacer esto con libc, libm, curses etc.

@cindex cabecera traductora
Está planeado un traductor automático de cabeceras que hará el encapsulamiento
en C superfluo. Este es un trabajo no trivial y no se está seguro de cuándo
será esto posible, así que tomará al menos algo de tiempo el que esté disponible.

@cindex compilación de código C
Puede asumir que el Compilador de C de GNU se usa para compilar los encapsulados y,
en general, cualquier código C que enlace a su código Pascal. La razón
para esta suposición es que sólo el Compilador C de GNU está garantizado que
tenga todas las convenciones compatibles con el Compilador Pascal GNU en cada
plataforma en la que funciona, coo comparten ambos el mismo backend. También, el
Compilador Pascal de GNU se contruye siempre junto con el Compilador C de GNU,
así que @samp{gcc} puede asumirse que está disponible donde lo esté @samp{gpc}.

@node Uso de Extensiones
@section Uso de Extensiones
@cindex extensiones no estándar

Se proporcionan multitud de facilidades en GNU Pascal que extienden el
lenguage Pascal estándar. El decidir si usar estas extensiones al
implementar su programa es una discusión tediosa.

Por un lado, el uso de estas extensiones puede hacer un programa
más limpio. Por el otro lado, la gente no será capaz de construir el
programa a no ser que tenga disponible el Compilador de Pascal de GNU.
Esto quizá haga que el programa no compile al usar otros compiladores.

En general, es mejor mantener compatibilidad con otros compiladores o
a los estándares del lenguaje, @emph{si esta compatibilidad es fácil
de lograr}.
En general, tristemente, para lograr compatibilidad se tienen considerables
desventajas. For ejemplo, quizá tenga que añadir cantidad de @samp{@{$ifdef@}}s
para tener compatibilidad con algunos compiladores no estándar, los cuales
hacen el código más difícil de leer, escribir, verificar y mantener. Además
los@samp{@{$ifdef@}}s en sí mismos son estensiones no estándar, así que no
se gana mucho de esta manera.

Al final, sugerimis no tomarse excesivas molestias  en la compatibilidadd.
Todos los interfaces del Compilador de Pascal de GNU (compilador y Run Time
System) son abiertos. Esto significa que pueden ser implementados para
otros compiladores cuando se necesiten o incluso los mismos fuentes pueden
ser usados gracias a que la licencia los preserva (lea más acerca de la
Licencia Pública General GNU en @uref{http://www.gnu.org/copyleft/gpl.html}),
en vez de enrrarecer el código no  usando las características extendidas.
Un elemplo (limitado) de esta estrategia está en la unidad  @samp{gpc-bp}
para  Borland Pascal, distribuída con el Compilador Pascal de GNU. Quizá
quiera echarle un vistazo a su interfaz para ver exactamente qué contiene,
Es fácil extenderlo para más características de compatibilidad cuando se
necesiten, aunque hay características que no pueden ser fácilmente emuladas
(en particular aquellas que tienen una sintaxis especial).

Por favor, no use las siguientes características, especialmente aquellas
que fuerom implementadas tan sólo para compatibilidad hacia atrás.

@itemize @bullet
@item
Los comentarios  @samp{(* *)} para los terminales antiguos donde los
caracteres @samp{@{} y @samp{@}} no estaban disponibles.

@item
las directivas  @samp{#} y los comentarios  @samp{//} comments, como en
C/Delphi. Si un fichero debe se usado en C, puede usar las directivas
@samp{#}, los condicionales de sintexsis de C, y los comentarios @samp{//}.
Un ejemplo (en este escrito, quizá cambien en el futuro) es
@file{p/rts/constants.h} en los fuentes del Compilador Pascal GNU.

@item
the misuse of typed constants as variables, which is a misfeature of
Borland Pascal.

@item
constantes carácter @samp{^A}. Use @samp{#1} o @samp{Chr (1)},
en su lugar.

@item
@samp{CString}s (excepto para interfaces C, desde luego)

@item
código compilado Borland Pascal como el siguiente en vez de usar
@samp{WriteStr}:

@smallexample
Str (Foo, s);
s := 'Hola ' + s;
@end smallexample

@item
la mayoría de los casos de @samp{FillChar} y @samp{Move}, excepto para código
de bajo nivel y cuando se aplique a caracteres dentro de una cadena. El uso de

@smallexample
FillChar (s, SizeOf (s), 0);
@end smallexample

para borrar una cadena, es incorrecto en  GNU Pascal e ineficiente incluso en
Borland Pascal, debido a que lo siguiente podría ser usado:

@smallexample
s := '';
@end smallexample

Esto tan sólo borraría el campo de longitud de la cadena @samp{s}.

@item
en la mayoría de los casos de  @samp{GetMem} y @samp{FreeMem} -- usualmente son un
arreglo para tipos schema no encontrados en otros compiladores.

@item
muchos casos de parámetros no tipados

@item
muchas rutinas hechas a mano relacionadas con nombres de ficheros. (Cuando se
escriben en  Borland Pascal, son aplicables normalmente en DOS, mientras que
las rutinas en la unidad @samp{GPC} proporcionan alternativas portables
para la mayor parte de este material).

@item
código ensamblador, excepto en áreas muy pequeñas para optimizaciones especiales
rodeadas por un @samp{@{$ifdef@}} específico (por ejemplo, para el tipo de
procesador). Pero entonces, proporcionar una versión  equivalente en Pascal plano
en la parte  @samp{@{$else@}} -- ¡y verificarla!

@item
cualquier cosa que requiera la unidad  @samp{System}.

@item
presuponer tamaños de los tipos

@item
presuponer la endianidad (algunos sistemas tienen los bytes de mayor y menor valor
en un orden diferente que otros sistemas, ; por favor lea el glosario  @xref{Glosario},
para una explicación)

@item
identificadores comenzando o finalizando con guiones bajos o teniendo varios
guiones bajos adyacentes

@item
unidades escritas sólo por compatibilidad con Borland Pascal. (@pxref{Unidades GPC,
, , GPC}) Nota, @samp{CRT} y @samp{Printer} son no sólo para compatibilidad
con Borland Pascal, sino también para uso general.

@end itemize

Los Estándares de Codificación GNU tienen buenas sentencias en este tema.
@xref{Uo de Extensiones, , , estándares}.

@node Comportamiento del Programa
@chapter Comportamiento del Programa para Todos los Programas

Este capítulo de los Estándares de Codificación GNU describen convenciones para
escribir software robusto. También describe estándares generales para mensajes
de error, el interfaz de línea de órdenesm y cómo deberían comportarse las
bibliotecas. Le animamos a leer esa parte de los Estándares de Codificacion GNU.
@xref{Comportamiento del Programa, , , estándares}.

Aquí están las notas especiales para la programación en Pascal, en cualquier caso.

@cindex funciones de señales
La elección entre funciones de señales, discutidad en los Estándares de
Codificación GNU, se hacen en el Run Time System así que no tiene que preocuparse por ellas.

@cindex verificaciones de error
Otra discrepancia con los Estándares de Codificación GNU es el comportamiento
predeterminado para verificación de errores que detecten condiciones ``imposibles''.
No sugerimos tan sólo abortar. Esto implica que cada usuario puede ser un programador,
pero no creemos que esto sea realista. Nuestra opción es imprimir un mensaje de error
razonable para que los usuarios puedan informar del descripciones del fallo a
los programadores que no se dieron cuenta del fallo por sí mismos o que no
podrían reproducirlo.

Además, los Estándares de Codificación de GNU sugieren verificar cada llamada de
systema para un error devuelto. Eso se aplica a C. En Pascal, la verificación de
error a menudo es automática, así que no necesita preocuparse de verificar
errores. Muchas rutinas de  E/S no devuelven un valor (por ejemplo, @samp{Reset}),
pero aquellas que lo devuelben deberían normalmente ser verificadas.

Desde luego, puede desactivar la verificación automática de errores y buscarlos
usted mismo. De hecho, algunos errores quizá causen que el programa
se aborte sin un mensaje de error. En su lugar, especialmente en unidades
o módulos, quizá quiera informar de errores y darle al usuario una oportunidad
de interenir y corregir las cosas. Para hacer esto, debe usar la directiva
del compilador @samp{@{$I-@}} , y verificar el valor de @samp{IOResult}
(@pxref{IOResult, , , gpc}) o las variables de error globales como
@samp{InOutRes} (@pxref{InOutRes, , , gpc}). Note que las rutinas de E/S
retornan inmediatamente si  @samp{InOutRes} está puesto, así que no es
necesario verificarlas después de cada operación, así que lo siguiente es
posible:

@smallexample
@{$local I-@}
Rewrite (f, 'bla');
WriteLn (f, 'foo');
WriteLn (f, 'bar');
WriteLn (f, 'baz');
Close (f);
@{$endlocal@}
if InOutRes <> 0 then
  begin
    WriteLn (StdErr, GetIOErrorMessage);
    @dots{}
  end;
@end smallexample

Sin embargo en su código quizá quiera también verificar  @samp{Rewrite} y
otras llamadas de apertura, las cuáles son las que tienden a fallar, y evitará
más llamadas innecesarias.

Hay un conjunto de rutinas en la unidad GPC para nombrar ficheros temporales,
ficheros de configuración y muchos otro material relacionado con nombres de
fichero. Las ventajas de usar éstos son que funcionan para distintas clases de
sistemas (por ejemplo Unix y DOS), y que los problemas futuros pueden ser
corregidos en un sólo lugar en el Run Time System en vez de en varios
programas o unidades diferentes.

En tanto en cuanto a las bibliotecas se refiere, sugerimos que no ponga cada
rutina en un fichero separado. Afortunadamente algún día el Compilador Pascal
de GNU hará esto automáticamente a nivel del enlazador. En este momento, creemos
que lo conveniente para el programador es mucho más importante que el tamaño del
binario. También recomendamos no usar un frefijo en el nombre, debido a que los
conflictos con los nombres pueden resueltos por identificadores cualificados
(@samp{UnitName.RoutineName}).
Hasta entonces, por favor utilice arreglos temporales cuando surjan conflictos.

@node Escritura en Pascal
@chapter Haciendo el Mejor Uso de Pascal

Este capítulo proporciona consejos acerca de cómo usar mejor el lenguaje Pascal
cuando escriba software. Por supuesto, las reglas se aplican al código publicado
únicamente -- si usted por ejemplo quiere comentar cosas fuera con comentarios
al estilo antiguo como  @samp{(* este *)}, debería hacerlo temporalmente y
quitarlos antes de distribuir su código. Sin embargo, si nunca sabe cuando se va
a publicar el código, es buena idea ceñirse a las reglas desde el principio.

@menu
* Clasificación de Indicaciones::     Clasificación de Indicaciones en Programación Pascal
* Verificación de Consistencia::      Uso de @code{Assert} para aborta si ocurre
                                      algo ``imposible''.
* Formato::                           Dar formato a su Código Fuente
* Comentarios::                       Comentar su Trabajo
* Orden::                             Orden de los Bloques de Código
* Mayúsculas::                        Capitalización
* Directivas del Compilador::         Uso de Directivas del Compilador
* Espaciado::                         Cómo usar espacios en su código
* Rupturas de Línea::                 Dónde romper su líneas de código
* Cadenas::                           Cadenas
* Internationalización::              Técnicas para internacionalización
* MemoryMap::                         Cómo usar con seguridad  @samp{MemoryMap}
@end menu

@node Clasificación de Indicaciones
@section Clasificación Indicaciones sobre Programación en Pascal
@cindex indicaciones clasificadas

Los nombres de los ficheros de código Pascal deberían tener el sufijo @samp{.pas}. El nombre
del fichero sin el sufijo debería usualmente corresponderse con el nombre
del programa/unidad/módulo, todo en minúsculas. Debería haber únicamente
un sólo programa/unidad/módulo en un fichero.

El código debe compilarse con el flag @samp{-Wall}, con y sin el flag
@samp{-O3} sin advertencias. (@xref{Directivas del Compilador}, para
saber cómo deshabilitar intencinalmente ciertas advertencias si es realmente necesario.)

No utilice la variable automática @samp{Result} en las funciones. Si quiere
una, declárela:

@smallexample
function Foo (@dots{}) = Bar: Integer;
@end smallexample

Utilice la declaración con  @samp{=}, no sin él, a no ser que quiera ser
estrictamente compatible con  PXSC.

Si una función devuelve un  @samp{Boolean} para indicar éxito, @samp{True}
debería significar éxito y  @samp{False} fracaso, a diferencia de algunas
rutinas de C donde  @samp{0} significa éxito.

Evite @samp{goto} y sentencias similares, como @samp{Exit},
@samp{Return}, @samp{Break}, @samp{Continue}. Evite @samp{goto} a
cualquier precio (excepto @emph{posiblemente} un @samp{goto} no local para
retornar desde funciones @emph{profundamente} anidadas, recursivas en caso
de error). Evite los otros si es posible con un esfuerzo razonable. Si ello
requiere una variable @samp{Boolean} adicional, esto cuenta como una excusa
para usar estas sentencias si realmente quiere. Nótese que a menudo, el
código se hace significativamente @emph{más simple} no usando @samp{Break}
etc. y usando en su lugar una condición de bucle mejor o una clase de
bucle diferente.

Nunca modifique los contadores de un bucle @samp{for}, o confíe en su valor
después del bucle. (Bien, esto no es meramente un estilo de codificación,
es la deficnición de Pascal. Hacer estas cosas producirán resultados indefinidos.)

Nunca confíe en comportamientos no definidos. Por ejemplo, que las variables
globales aparenten estar inicializadas a  @samp{0} al comienzo de un programa,
o quizás que algunas veces la memoria reservada nueva aparente estar
inicializada, o que los contadores de bucle @samp{for} aparenten tener
cierto valor después del bucle -- nada de esto está garantizado, y puede
cambiar con cada compilador, plataforma o versión. Indefinido significa indefinido,
de hecho estas cosas quizá parezcan funcionar en todos los sistemas que ha
verificado y con otros 42 compiladores signifique exactamente nada.

En comparación, ponga la expresión ``más variables'' en el lado izquierdo:

@smallexample
for i := 1 to 10 do
  if a[i] = Foo then
    for j := 1 to 10 do
      if b[j] = a[i] then @dots{}
@end smallexample

Considerando la segunda línea  del ejemplo de arriba, la expresión a la
izquierda  (@code{a[i]}) varía en cada vuelta, pero el lado derecho
(@code{Foo}) no. (En este caso asumimos que  @code{Foo} es una constante
o una función que no depende de  @code{i} u algún otro dato global.
De otra forma quizá tendría más sentido poner @code{Foo} a la izquierda,
y quizá usar un comentario extra para hacer notar esto.)

la última línea del ejemplo de arriba quizá parezca extraña, porque
@code{b[j]} y @code{a[i]} quizá parezcan como si tuviesen el mismo
nivel de ``variablidad''. Pero de hecho, @code{j} varía más a menudo que
@code{i}, ya que cada vez que  @code{i} cambia, @code{j} ha cambiado
ya 10 veces.

Evite la duplicación de código. Es sencilo copiar el código, pero convierte
el mantenimiento en una pesadilla al tener que cambiar varios lugares
similares. Use rutinas o subrutinas, unidades o módulos, lo que sea. Planifique
cada parte del código para que pueda ser extendido. No ponga demasiados trucos
en lugares que serán probablemente modificados más tarde.

No rodee sentencias simples con @samp{begin} y @samp{end},
a no ser que tenga que evitar el problema del else colgante o que la
única línea forme el cuerpo de una rutina completa. Vea los ejemplos siguientes:

@smallexample
if foo then
  begin
    if bar then
      baz
  end  @{ Avoid the dangling else problem. @}
else
  qux  @{ Single line statement. @}
@end smallexample

No escriba inicializadores de unidad  vacíos. Esto es lo que @emph{no} se debe hacer:

@smallexample
@dots{}

procedure Foo;
begin
  @dots{}
end;

begin
end.
@end smallexample

En su lugar, simplemente:

@smallexample
@dots{}

procedure Foo;
begin
  @dots{}
end;

end.
@end smallexample

No escriba declaraciones que no se usen, excepto en los interfaces que están
destinados a ser usados por el importador.

@cindex booleanos
Recuerde que los  @samp{Boolean}os son @samp{Boolean}os. Por favor use @samp{if
Foo then} en lugar de @samp{if Foo = True then}, y @samp{if not Foo
then} en vez de @samp{if Foo = False then}. Además, emplee @samp{until
False} en lugar de @samp{until 1 = 0} -- esto parece más inteligente. Otra
situación común es @samp{Foo := Expression} en vez de @samp{if
Expression then Foo := True else Foo := False}.

Evite duplicar identificadores globales, por ejemplo no sobrecargue un
identificador integrado, aunque el Compilador de GNU Pascal permite esto,
y no utilice el mismo identificador global en varias unidades o módulos. (Esta
característica es presente en el Compilador Pascal de GNU
llamándose ``identificadores cualificados'' pero todavía no la use.)

@cindex variables globales
Desalentamos el uso de variables globales para propósitos no globales
(e.g., el uso de una variable @code{Contador} usada como un contador en
varias rutinas locales). Declare una variable contador para cada rutina
que lo necesite, es su lugar. En general, esto también permite una mejor
optimización del código generado.

@cindex bucles infinitos
Cuando necesite un bucle infinito (que pueda ser abandonado con
@samp{Break}), le sugerimos que utilice un @code{repeat} mejor que un bucle
@code{while} porque desplaza el código menos a la derecha (al menos si hay
más de una sentencia dentro del bucle). Esto es:

@smallexample
repeat
  @dots{}
until False
@end smallexample

En vez de:

@smallexample
while True do
  begin
    @dots{}
  end
@end smallexample

@node Verificación de Consistencia
@section Verificación Explícita de la Consistencia Interna
@cindex verificación de consistencia
@cindex assert

Al igual que se establece en la documentación de la biblioteca de C
(@pxref{Verificación de Consistencia, , , libc}),  cuando se escribe
un programa, a menudo es una buena idea poner verificaciones para
las violaciones de asunciones básicas.
Considere el siguiente código en Pascal:

@smallexample
procedure HacerAlgoEnAPString (StrPtr:PString);
@end smallexample

Puede asumir implícitamente que el procedimiento anterior nunca será
llamado con @code{nil} como argumento, pero es más seguro verificar
la ``condición imposible'', por ejemplo, verificando que
@samp{StrPtr} es distinto de @code{nil}, de este modo:

@smallexample
procedure HacerAlgoEnAPString(StrPtr:PString);
begin
  Assert (Str<>nil);
  @dots{}
end;
@end smallexample
Cuando esta verificación falla, el programa produce un error en
tiempo de ejecución. Entonces puede deducir que el código que llama
a este procedimiento es defectuoso (o que necesita extender esta
rutina en particular), así que esto puede ser muy útil para
localizar el problema. En otras palabras, verificar asunciones
básicas al principio del cuerpo de una rutina u otro lugar
estratégico es la manera correcta de asegurarse de que una función
no será usada de fora equivocada.

La biblioteca de C de GNU proporciona la macro @code{assert} para
esta clase de verificaciones. GNU Pascal proporciona su contraparte
Pascal que se llama @code{Assert}, la cuál se comporta de manera un
poco diferente. @code{Assert} no abortará su programa, sino que
causará un error en tiempo de ejecución (@pxref{Assert, , , gpc}) el
cuál, podrá por ejemplo, atraparlo usando la unidad @samp{Trap}
(@pxref{Trap, , , gpc}).

Una vez que piense que su programa está depurado, puede desactivar
las verificaciones de errores efectuadas por la rutina @code{Assert}
mediante la recompilación con el indicador @samp{--no-assertions}.
No se necesita ningún cambio en el códigopara desactivar estas
verificaciones. Los efectos laterales en el argumento a
@samp{Assert} todavía son evaluados (a diferencia de C), así que es
correcto escribir:
@smallexample
Assert (MiFuncion (Foo,Bar) > 0)
@end smallexample

Esto siempre llamará a @code{MiFuncion}, pero sólo se asegurará que
el resultado es positivo cuando no se de @samp{--no-assertions}.

Sin embargo, se recomienda que no desactive la verificación de
consistencia a no ser que no pueda consentir que el programa se
ejecute un poco más lentamente.

@node Formato
@section Dar Formato a su Código Fuente
@cindex formateado del código fuente

@cindex espacios
@cindex blancos
Lo primero de todo, evite espacios innecesarios al final de las líneas.
También recuerde no salvar el fichero con caracteres TAB, debido a que
diferentes editores o diferentes configuraciones los interpretarán con
una cantidad diferente de espacios, rompiendo entonces la indentación.
(Si usa GNU Emacs, la función @samp{untabify} es útil; si usa VIM, la
opción @samp{expandtab} (@samp{:set et}); en PENG, puede usar la opción
@samp{Expand tabs}.)

@cindex caracteres de control
Por favor evite el uso de cualquier carácter de control, excepto el de
lína nueva, por supuesto. Esto significa nada de caracteres de
alimentaciónd e formularios (@samp{#12}), o caracteres de página nueva.
Estos se recomiendan en los Estándares de Codificación de GNU para
separar las partes lógicas de un fichero,pero no los use al menos en
código Pascal. No use el carácter  @samp{SUB} ni el (@samp{#26}),
utilizado incorrectamente en DOS como indicador de finde fichero. Los
editores antiguos de DOS ponían este carácter al final de cada fichero
sin ninguna buena razón, aunque el sistema de ficheros FAT sabe
acerca del fin de un fichero por sí mismo.

@cindex longitud de línea
Recomendamos una longitud de línea máxima de 68 caracteres, de esta manera
puede ser impreso en @TeX{} con el tipo predeterminado en A4, o 78 caracteres,
para las pantallas de 80 columnas de ancho. Esta no es una regla fija porque
las líneas rotas a menudo decrementan la legibilidad del código fuente.

@cindex líneas vacías
Utilice líneas vacías entre bloques. Los bloques sin comentarios largos,
secciones @samp{type}, @samp{const}, @samp{var}, @samp{label}, cuerpos
de rutinas, inicializadores/finalizadores de unidades/módulos,  líneas
@samp{program}, @samp{unit}, @samp{interface}, @samp{implementation},
@samp{module}, @samp{export}, @samp{uses}, @samp{import}, directivas
globales del compilación. Junto a los comentarios largos que se refieran
a la siguiete declaración, ponga sólo una línea vacía antes del comentario,
no entre el comentario y la declaración misma. Una excepción especial es
entre bloques dentro de la misma rutina -- no use líneas vacías allí.
Por ejemplo:

@smallexample
procedure Short;
var
  Foo: Integer;
  Bar: Char;
begin
  @dots{}
end;
@end smallexample

Pero recuerde usar líneas vacías para separar subrutinas, como lo siguiente:

@smallexample
procedure Long;
const
  @dots{}
var
  variables usadas por Sub @dots{}

  procedure Sub;
  var
    @dots{}
  begin
    @dots{}
  end;

var
  variables no usadas por Sub @dots{}
begin
  @dots{}
end;
@end smallexample

Nótese que no debería ponerse una línea vacía después de la
declaración de la rutina principal, a no ser que le siga
inmediatamente una declaración de subrutina. Si se hiciera al
contrario, la declaración de la rutina principal podría semejarse
a una declaración ``forward''.

Dése cuenta que en el fragmento de código de arriba separamos las
variables locales (o constantes) antes y después de la subrutina -- esto
no es obligatorio.

Desde luego, lo que dijimos para las subrutinas es válido también para
sub-subrutinas de cualquier profundidad.

Debería ponerse una línea vacía entre declaraciones del mismo tipo,
donde sea apropiado, para separarlas lógicamente. En caso de que haya
un comentario antes de la declaración, la línea vacía debe estar antes
del comentario. En caso contrario, la línea vacía va antes de la
declaración.

Las líneas vacías pueden ser usadas en comentarios largos para separar
parágrafos.

No se ponen líneas vacías al principio o al final de un fichero, sólo una
línea nueva al final. No múltiples líneas nuevas.

@node Comentarios
@section Comentar Su Trabajo
@cindex comentarios

los comentarios deberían ser colocados entre llaves como esto:

@smallexample
@{ Este es un comentario bonito. @}
@end smallexample

No utilice los comentarios del estilo antiguo entre paréntesis y asteriscos,
como esto:

@smallexample
(* Este es un comentario feo. Uno de los que no debe escribir. *)
@end smallexample

También, no use comentarios introducidos por una barra oblicua doble:

@smallexample
// Otra clase de comentario que no debe escribir.
@end smallexample

Aunque Pascal ISO explícitamente permite comentarios mezclados, el
Compilador de Pascal de GNU no los acepta a no ser que active la opción
con la directiva de compilador apropiada @samp{@{$mixed-comments@}} --
pero debe quere hacerlo. Aquí se muestran un par de ejemplos de comentarios
mezclados que no debería seguir:

@smallexample
(* Este ... @}
@end smallexample

@smallexample
@{ ... y ese. *)
@end smallexample

@cindex comentarios anidados
También, intente evitar comentarios anidados como @samp{@{ @{ Este otro @} @}}.
Estos son correctos si quiere poner algún @TeX{} en un comentario o algo más
exótico. Si por cualquier razón tuviera que usar comentarios anidados,
necesitará activar la opción con el interruptor del compilador apropiado,
que es  @samp{@{$nested-comments@}}. No utilice la opcion de línea de órdenes
@samp{--nested-comments}. Ponga esta clase de opciones en el fuente para que
cualquiera intentando compilarlo no tenga que adivinar qué  opciones de línea de
órdenes se necesitan, y porque las opciones de línea de órdenes afectarían a
 @emph{todos} los ficheros fuente, por ejem. cuando compile un proyecto con
varios módulos/unidades.

@cindex idioma de los comentarios
Por favor, escriba los comentarios en sus programas en inglés, porque
el inglés es el único idioma que casi todos los programadores en todos
los países pueden leer. Si no escribe bien en inglés, por favor escriba
los comentarios tan bien como pueda y entonces pida a otras personas que
le ayuden a reescribirlos. Si no puede escribir comentarios en inglés,
por favor, encuentre a alguien que trabaje con usted y le traduzca los
comentarios al inglés.

@cindex espaciado de los comentarios
Debería adoptar ``Espaciado francés'', por ejem. sólo un espacio al final de
la frase. De esta manera, no puede usar el @samp{M-a} de GNU Emacs y la
combinación de teclas @samp{M-e} para moverse a través de la frase. Esperamos
que pueda vivir sin ello. Además, por favor ponga únicamente un espacio después
de la llave de apertura del comentario y antes de la llave de cierre.

@cindex emplazamiento de los comentarios
Si un comentario se refiere únicamente a una línea de código, posiblemente
escríbalo después de la línea de código, en la misma línea, separado del
código por dos espacios. Esto está también permitido para la sección de
interfaz de una unidad y para las variables globales. Más a menudo querrá
escribir esta clase de comentarios detrás de los campos de registro/objeto.
En otros casos, los comentarios van en una o más líneas propias, como esto:

@smallexample
@{ foo bar baz @}
@end smallexample

O:

@smallexample
@{ foo bar
   baz @}
@end smallexample

O Con parágrafos:

@smallexample
@{ foo bar
   baz

   qux @}
@end smallexample

Los comentarios necesitan ser colocados antes del código que describenm y
necesitan tener el mismo nivel de indentación. Este ejemplo debería
hacer esto claro:


@smallexample
@{ Mis tipos. @}
type
  @dots{}

type
  @{ Mis primeros tipos. @}
  @dots{}

begin
  @{ Mi primera sentencia. @}
  Bla;
  @{ Inicio del bucle. @}
  repeat
    @{ Cuerpo del bucle. @}
    @dots{}
  @{ Finaliza cuando Algo ocurre. @}
  until Algo
end;
@end smallexample

Nótese la posición para el comentario  @samp{until}.

Los comentarios describiendo una declaración global deberían estar en
una o más líneas propias, inmediantamente antes de la declaración. Por ejemplo:

@smallexample
@{ Esto es  Foo. Hace esto y lo otro. @}
procedure Foo;
@end smallexample

@cindex comentarios estúpidos
@cindex comentarios triviales
No escriba comentarios ``triviales'' como los que se listan en los ejemplos anteriores.
Debería evitar los comentarios escribiendo código claro. Linus Torvalds apunta esto
remarcadamente en el Estilo de Codificación del Núcleo:

@quotation
Los comentarios son buenos, pero también está el peligro de la sobrecomentación.
@strong{Nunca} intente explicar @strong{cómo} funciona el código en un comentario:
es mucho mejor escribir código en que el @emph{funcionamiento} sea obvio, y es un
desperdicio de tiempo explicar código malamente escrito.
Gereralmente, se quiere que los comentarios digan @strong{qué} hace el código
no @strong{cómo}.
@end quotation

(Note que nosotros nos desviamos un poquito del estilo de codificación de Linus.)

@cindex comentarios acerca de código no obvio
@cindex comentarios de las peculiaridades
El código ``peculiar'', ``Tricky'' es equivalente a ser comentado. Definimos
como ``peculiar'' el código que hace cosas que no som obvias, basándose
en asunciones no obvias, tiene implicaciones no obvias, hay algo que notar
cuando se cambie, no es lo que parace a primera vista, tiene un efecto
lateral, o requiere que otra parte del código fuente sea cambiada simultáneamente
con él.
El codigo peculiar debería seer usado muy de vez en cuando.

@cindex comentarios a fuentes externas
En el caso de que el comentario se refiera a algun otro lugar en el código,
sea en el mismo fichero o en uno diferente, por favor refiérase a él
no por el número de línea (esto cambiará muy a menudo) sino por el nombre
de la rutina o el contexto. Además, piense si es útil poner un comentario
en el otro lugar refiriéndose a éste. (No siempre, pero a veces esto nos ha
sido útil).

@cindex comentar código
Para comentar partes del código que no deban compilarse, necesita rodearlas con
@samp{@{$if False@} @dots{} @{$endif@}} en vez de usar un comentario.

@cindex comentarios para separar partes lógicas
Para separar partes lógicas dentro de módulos grandes o unidades, puede usar un
comentario especial -- sugerimos un patrón fijo que sea fácilmente encontrable:

@smallexample
@{@@sección Nombre de la sección@}
@{@@subsección Nombre dela subsección@}
@end smallexample

Nótese que ningún espacio sigue a la llave de apertura o precede a la llave de
cierre en este caso.

@cindex comentarios descriptivos
Un módulo o unidad o biblioteca debería tener un comentario para cada una de las
declaraciones del interfaz, de manera que la parte del interfaz del fichero
fuente sea una fuente de documentación confiable. Esto es opcional para cualesquiera
declaraciones introducidas únicamente en la sección de implementación o en
@samp{program}as. Por supuesto, varias declaraciones relacionadas (ej: grupos
de constantes) pueden compartir un comentario.

@cindex comentarios con marcas
Una utilidad llamada @samp{pas2texi} será escrita para construir ficheros
Texinfo desde los comentarios Pascal. Esto permitirá ciertas clases de
marcado dentro de los comentarios. Serán escritos en la documentación de
@samp{pas2texi} y/o en versiones futuras de este documento.

@cindex comentarios fixme
Puede usar comentarios ``fixme'', (``arréglame'') para apuntar cosas que deben
ser arragladas en el código, o en una biblioteca (o módulo, o unidad, o compilador
usado) que afecte directamente al código, requiriendo un arreglo. Estos comentarios
son frefijados por al menos dos @samp{@@} -- añada tantos @samp{@@} como la urgencia
de la publicación se incremente.

Estos comentarios pueden contener más o menos detalles oscuros acerca del problema,
especialmente si la raíz del problema está por cualquier parte. Por ejemplo,
el comentario  @samp{@{ @@@@fjf226 @}} declara el siguiente código como un arreglo
para un problema del Compilador de Pascal de GNU que es demostrado por
el programa de prueba del Compilador de Pascal de GNU @samp{fjf226.pas}. (Es un fichero
que puede encontrar en el paquete de fuentes del Compilador de Pascal de GNU.)

Los comentario ``Fixme''no deberían mezclarse con comentarios ordinarios. Si
necesita ambas clases, aúselos separadamente, incluso si directamente después de
cada uno. Pueden usarse en cualquier lugar, incluso dentro de sentencias, debido a
que tienen naturaleza temporal. Más a menudom suelen caer en el cuerpo,
a no ser que inluencien a interfaces. En particular los interfaces deberían
cambiar debido a un comentario @samp{@@@@} inmediatamente antes de su comentario
de descripción.

@node Orden
@section Orden de los Bloques de Código
@cindex orden

Por favor, comience cada fichero con un comentario conteniendo, en este orden:

@itemize @bullet
@item
una breve descripción diciendo qué hace el código en el fuente
@item
una descripción larga yendo al detalle sobre el código y especificando
fuentes de informacion o código
@item
una notificación del copyright sostenido por los autores del código
@item
la licencia -- desde luego quiere usar la Licencia Pública General GNU
o la Licencia Pública General Menor para sus programas y unidades, no?
@end itemize

@cindex bloques de declaración
En general, debería seguir este orden para los bloques de declaraciones:

@itemize @bullet
@item
@samp{const} declaraciones
@item
@samp{type} declaraciones
@item
@samp{var} declaraciones
@item
@samp{label} declaraciones
@item
rutinas
@end itemize

Puede desviarse de este orden cuando sea necesario o haga el código más
legible. Esto es un ejemplo donde el orden no puede ser respetado:

@smallexample
type
  TSomething = record
    This, That: Integer
  end;

const
  SomeConst = SizeOf (TSomething);
@end smallexample

Las reglas de arriba se aplican a los bloques de declaración dentro de
rutinas también.

Cuando hay varias partes, más o menos independientes, especialmente en
una unidad grande o un módulo, puede aplicar este orden dentro de cada
parte. No ponga, por ejemplo, constantes de todas las partes juntas. Debe
mantener el código legible.

@cindex declaración de variables
Las variables que son usadas solamente en el programa principal deben
ser declaradas globalmente en Pascal. sin embargo, GNU Pascal ofrece
unaextensión para declarar variables en lugares arbitrarios del código
(@pxref{var, , , gpc}). En este caso, en contraste con la regla general
anterior, a menudo es mejor poner su declaración justo antes del
@samp{begin} del programa principal, despue todas las rutinas, etc.,
especialmente cuando hay más que unas pocas variables y el tamaño del
fichero fuente no es pequeño. Así, el bloque de declaración de variables
es más fácil de ver y cambiar para el programador cuando edita el programa
principal, y puede asegurarse de que las rutinas no  lo usan accidentalmente.

@cindex declaraciones dentro de declaraciones de tipo
Cuando declara un tipo junto con su tipo de puntero, declare el
puntero primero. Es más fácil de reconocer, especialmente si el tipo
es un registro largo o un objeto. además, hace posible el uso de estructuras
recursivas /por ejemplo, usando punteros a un tipo dentro de su tipo). Debería
anteponer un  @samp{T} al nombre del tipo y una @samp{P} al tipo de puntero
asociado. Vea el ejemplo:

@smallexample
type
  PMyInt = ^TMyInt;
  TMyInt = Integer;

  PStrList = ^TStrList;
  TStrList = record
    Next: PStrList;
    s: TString
  end;
@end smallexample

Nótese  que el campo  @samp{Next} se especifica primero. Sugerimos siempre
ponerlo como el primer campo en tipos recursivos, así permite algunas
rutinas genéricas de listas y quizá sea un poco más eficiente recorrer
por ejemplo, sin offsets.

Sugerimos poner todos los tipos punteros dentro de cada declaración @samp{type}
en primer lugar, aunque no consideramos esto imperativo. Este es un ejemplo:

@smallexample
type
  @{ Pointer types @}
  PFoo = ^TFoo;
  PBar = ^TBar;
  PBaz = ^TBaz;

  @{ Some custom integer types @}
  TFoo = Integer (16);
  TBar = Cardinal (16);
  TBaz = Cardinal (32);
@end smallexample

@cindex declaraciones dentro de tipos objeto
Dentro de tipos objeto puede haber tres areas de declaración. Hay tres palabras reservadas
para introducir estas áreas: @samp{public}, @samp{protected}, @samp{private}. Dentro de
En el interior de cada una de estas áreas se sigue este orden:

@itemize @bullet
@item
campos
@item
constructores
@item
destructor (debería haber sólo uno)
@item
métodos
@end itemize

@cindex orden en la implemantación
En la parte de implementación del objeto, ponga los cuerpos de rutina
en el mismo orden en que aparecen en la declaración del interfaz. Esto
también se aplica a unidades y módulos, en los cuáles la implementación
debería reflejar las declaraciones del interfaz.

No use el @samp{;} de cola al final de un bloque, por ejem. antes de
@samp{end}, @samp{until}, etc. excepto en  @samp{case} -- la última rama
antes de la rama @samp{else}  (o la última rama si no hay rama @samp{else})
@emph{debería} tener un @samp{;}, para evitar problemas como:

@smallexample
case @dots{}
  Foo:
    if Bar then  @{ later inserted @}
      begin
        @dots{}
      end  @{ si no hay punto y coma aquí @dots{} @}
  else  @{ @dots{} esto será confundido como el @samp{else} del @samp{then} @}
    @dots{}
@end smallexample

(Lo mismo si el @samp{if} estaba aquí para antes y la rama @samp{else}
del @samp{case} se inserta después.)

En un oibjeto, puede parecer extraño omitir el  @samp{;} después del
último elemento que es a menudo un método. Sin embargo lo permitimos,
y por consistencia, también en los registros.

@node Mayúsculas
@section Mayúsculas
@cindex Mayúsculas

Las palabras reservadas deberían estar todas en minúscula, incluyendo
directivas, por ejem. palabras que están reservadas sólo en algunos
contextos, como @samp{protected}. Si usa directivas como identificadores (lo
que es como causerte un dolor) fuera de sus contextos, escríbalas como
identificadores.

Como excepción especial, puede usar @samp{File} empezando por mayúscula cuando
sea usado como un tipo propio, por ejem, como en  @samp{file of Char}.
Lo mismo no puede decirse para  @samp{procedure} como un tipo (estilo Borland Pascal)
debido a que @samp{File} puede ser un tipo propio, mientras que @samp{procedure}
es un tipo constructor, por ejemplo:

@smallexample
procedure Foo (var a: File);  @{ Esto Funciona. @}
procedure Foo (var a: procedure);  @{ Esto no. @}
@end smallexample

@cindex mayúsculas en los identificadores
La siguiente cuestión es la escritura de identificadores. No hay diferencia entre
los identificadores integrados y los definidos por el usuario. Sólo la primera
letra debería ser mayúscula, o, si hay palabras concatenadas o acrónimos , la
primera letra de cada palabra debería ponerse en mayúsculas -- no emplee guiones
bajos. Los acronimos que se han convertido en parte del lenguaje natural pueden
escribirse de la misma forma. Por ejemplo, @samp{Dos} o @samp{DOS}; pero siempre
@samp{GPC}, not @samp{Gpc}. Here are some examples of identifiers:
@samp{Copy}, @samp{Reset}, @samp{SubStr}, @samp{BlockRead},
@samp{IOResult}, @samp{WriteLn}, @samp{Sqr}, @samp{SqRt},
@samp{EOF}, @samp{EOLn}.

@cindex capitalización de las constantes
Estas reglas se aplican a los identificadores de constantes también,
como las macros de C

También dése cuenta que los identificadores muy pequeños pueden
escribirse en minúsculas, como @samp{i} o @samp{s1} o @samp{xx}. Dichos
identificadores cortos deberían ser usados sólo localmente. Pueden ser
usados para parámetros de rutinas globales, porque el ámbito de dichos
parámetros es local también, y sus nombres de hecho no importan para
nada a quien los llame. El uso de estos identificadores en un contexto
global debería ser evitado, especialmente en unidades o módulos o
bibliotecas (porque el autor no sabe en qué contextos serán usadas).

Por favor, sea consistente en el uso de las mayúculas. Sabe que Pascal
no se quejará si cambia la capitalización de un identificador a través
del código, pero por favor, cíñase a la misma capitalización.

@cindex tipos enumerados
@cindex constantes
Para los identificadores de los valores de los tipos enumerados y para
bloques de constantes, por ejemplo, lugares donde se introducen muchos
identificadores, puede ser útil usar un prefijo de dos letras minúsculas
y  @samp{_}, en contraste con las reglas anteriores:

@smallexample
type
  TFooBar = (fb_Foo, fb_Bar, fb_Baz, fb_Qux);
@end smallexample

@smallexample
@{ My Foos @}
const
  mf_Foo = 1;
  mf_Bar = 3;
  mf_Baz = 42;
@end smallexample

@cindex POO
En código orientado a objetos (especialmente en constructores), a menudo
existe la necesidad de tener un parámetro correspondiente a un campo
de un objeto (ej. para pasar un valor con el cual inicializar el campo).
Como ambos no pueden llamarse de la misma manera, el campo debería tener
el nombre ``natural'' debido a que es normalmente empleado en más rutinas,
y el nombre del parámetro debería ser ``cambiado''. FIXME: Todavía no
hemos encontrado una regla realmente satisfactoria para este cambio
(algunos usan @samp{a} como un prefijo), y si usted tiene alguna idea,
déjenos conocerla.

@cindex capitalización de macros
En tanto a lo que concierne a las macros, recomendamos encarecidamente
que no las use. Por favor, no use macros en sus programas. Intente evitar
el uso de macros en sus programas, porque son el mal. Creemos que no debe
usar macros en su código. Dicho esto, si todavía osa a usar una macro,
escríbala en mayúsculas completamente y separe las palabras con guiones
bajos (_). Debido a que las macros no siguen las reglas de visibilidad
de Pascal, tiene sentido escribirlas de forma diferente. Esto se aplica
a los condicionales también.

@node Directivas del Compilador
@section Uso de Directivas del Compilador
@cindex directivas del compilador

Gereralmente sugerimos que use tan pocas directivas del compilador como
sea razonablemente posible, porque hacen el código más difícil de entender
(ej. cuando verifica efectos laterales) y de modificar (ej. cuando se
mueven partes del código dentro o fuera del ámbito de las directivas
del compilador). Las directivas deberían ser invocadas como en el
siguiente ejemplo:

@smallexample
@{$su_directiva_de_compilacion@}
@end smallexample

Definitivamente no de esta manera (@pxref{Comentarios}):

@smallexample
(*$no-use-asi-una-directiva-de-compilacion*)
@end smallexample

Además, definitivamente no de esta manera que es dependiente de los saltos
de línea, en Pascal normalmente es:

@smallexample
#su-directiva-de-compilacion
@end smallexample

Lo mismo sirve para definiciones de macros:

@smallexample
@{$define @dots{}@}
@end smallexample

Esto ahorra la barra invertida antes de los saltos de línea, en contraste con
@samp{#define}. Pero no va a usar macros, ¿verdad?
(@pxref{Mayúsculas})

@cindex espaciado de las directivas
Es lo que concierne al espaciado no escriba un espacio antes del cierre de
llave, así como no ponga uno después de la llave de apertura. Si concatena
varias directivas juntas, no ponga un espacio entre cada una de ellas, una
sola coma es suficiente.

@c FIXME
@c
@c Maybe someone has good reasons to use the space after the commas.

@cindex comentarios y directivas
No introduzca comentarios dentro de las directivas. Escríbalos separados,
como esto:

@smallexample
@{$X+@}  @{ Necesitamos sintaxis extendida. @}
@end smallexample

Borland Pascal permite mezclar comentarios con directivas, pero
realmente es un mal uso.

Formas cortas para llamar directivas están bien, pero las formas
largas son por lo menos tan buenas como las otras, así que siga su preferida.
Las formas cortas deben ser escritas en mayúsculas mientras que las formas
cortas lo son en minúsculas (excepto para argumentos sensibles a la capitalización
como mensajes y nombres de fichero -- por supuesto, los nombres de fichero deben
tratarse siempre como dependientes de la capitalización, incluso en DOS, para
preservar la portabilidad del código).

Puede combinar varias directivas, además mezclar las cortas con las largas, en
una sola llamada, por ejemplo como las siguientes:

@smallexample
@{$gnu-pascal,I-,X+@}
@end smallexample

@cindex directivas estándar
Cualquier unidad o module debería tener @samp{@{$gnu-pascal,I-@}} o
@samp{@{$gnu-pascal,I+@}} cerca del principio (tras el comentario de la
cabecera con la desripción y licencia). @samp{@{$gnu-pascal@}} permite
que la unidad sea compilada sin opciones de dialecto incluso si el programa
principal está compilado con alguno. @samp{@{$I-@}} o @samp{@{$I+@}} indica
al usuario (incluso aunque uno de ellos está predeterminado) si la unidad
maneja/devuelve errores de esntrada/salida o permite que éstos causen errores
en tiempo de ejecución. La forma es preferible para la mayoría de las unidades
(rutinas que devuelven errores de entrada/salida deberían declararse como
 @samp{iocritical} cuando esto sea soportado).
Para programas, este item es opcional.

@cindex directiva no-warning
@samp{@{$W-@}} (sin advertencias) debe usarse localmente y debe tener
un comentario ``fixme''  (@pxref{Comentarios}) porque ello indica un problema
con el código o el compilador. Si está disponible, use directivas para desactivar
ciertas advertencias acerca de problemas del compilador. Por ejemplo,  @samp{@{$W
no-object-directives@}} o @samp{@{$W no-field-name-problem@}}. Estas
directivas particulares pueden usarse globalmente.

Por favor, no deshabilite las advertencias cuando sea tan vago de no escribir
código que no produzca advertencias.

@cindex directivas locales
Cualquier flag del compilador que no se haya puesto globalmente (por ejemplo con
@samp{@{$gnu-pascal@}}, vea arriba) sebería ponerse como @samp{@{$local
@dots{}@}}. En otras palabras, no de esta manera:

@smallexample
@{$I-@} Reset (f); @{$I+@}
@end smallexample

Pero sí de esta otra:

@smallexample
@{$local I-@} Reset (f); @{$endlocal@}
@end smallexample

La forma esa equivocada si  @samp{@{$I-@}} ya fue puesto. Incluso si un programador
pudirera darse cuanta y tener en cuenta de  cual es la configuraci global,
esto quizá camiará alguna vez, o parte del código puede ser copiado o movido.
La última forma es más segura en estos casos.

Para hacerlo incluso más claro, de las dos últimas reglas que sigen:

@smallexample
@{$local W-@} Foo; @{$endlocal@}  @{ @@ GPC produces a superfluous warning @}
@end smallexample

Otra vez, intente evitar directivas locales. @samp{@{$I-@}} se necesita
algunas veces. @samp{@{$X+@}} puede usarse si @emph{realmente}, @emph{realmente}
es necesario (tan localmente como sea posible): evite aritmética de punteros.

@cindex verificaciones de retorno
No use  @samp{@{$X+@}} para ignorar resultados de funciones, no use
@samp{@{$ignore-function-results@}}, en cualquier caso. Es muy fácil
ignorar un resultado que no debería ignorar. Algunas veces, especialmente
cuando enlaza a una biblioteca externa de C, quizá tenga que tratar con
funciones que tienen un resultado superfluo, que probablemente no
quiera verificar. Puede declarar dichas funciones con el atributo especial
@samp{ignorable}, cuando esté disponible, así que sus resultados son
silenciosamente ignorados. Por el momento, use una variable desechable.

También use variables desechables si no quiere ignorar el resultado de una
llamada particular a una función cuyo resultado en general debería no ser
ignorado. En esos caso sverifique cuidadosamente que el resultado puede
ser en efecto ignorado de forma segura. Si por ejemplo, un resultado no esperado
podría indicar una situación ``imposible'', es normalmente mejor verificar
el resultado e imprimir una advertencia a abortar en el caso inesperado, al menos
si @samp{DEBUG} está definido (@pxref{Directivas del Compilador}).

@cindex directivas del enlazador
Las directivas del enlazador, ej. @samp{@{$L@}} para bibliotecas y código
fuente C (u otro lenguaje) deberían ser puestas cerca del principio en programas
y cerca de la línea  @samp{implementation} en unidades o módulos.
Varias bibliotecas, ficheros fuente C en una directiva son posibles cuando
pertenecen a un mismo conjunto lógico (por ejemplo, una biblioteca y sus
wrapers de C), pero no para cosas distintas. Esta directiva no debería mezclarse
con otras directivas (que incluso no funcionarían si @samp{L} viene primero --
la otra manera quizá funcione, pero no debería usarse). La declaración externa
de la biblioteca o rutina C debería seguir inmediatamente la directiva (excepto
en una unidad o módulo para aquellos que van en el interfaz). El uso de
@samp{@{$L@}} en programas no es una buena idea a menudo, hacer una unidad es
a menudo mejor por abstracción y reutilización.

@cindex compilación condicional
La compilación condicional quizá sea útil algunas veces, pero debería usar
tan pocos @samp{@{$ifdef@}}s como sea posible, debido a que disminuyen
la legibilidad. Cuando se usan condicionales para diferencias entre sistemas,
verifique características (por ejemplo, @samp{__BYTES_LITTLE_ENDIAN__}) o
grupos de sistemas (por ejemplo, @samp{OS_DOS}) en vez de sistemas individuales,
para incluir mejor a los sistemas que no conoce o que no existan ahora.

Si es posible (esto quizá no esté disponible), utilice las constantes
predefinidas (por ejemplo, @samp{BytesBigEndian}, @samp{OSDosFlag})
en lugar de definiciones -- para el código en que sea posible (la rama ``siempre
falsa'' será optimizada, pero todavía tendrá su sintaxis verificada como beneficio
aunque no use el preprocesador); para declaraciones de tipos no es usualmente posible
y se tienen que usar definiciones. Un buen ejemplo es la declaración
de @samp{TWindowXY} en la unidad CRT. Vea:

@smallexample
TWindowXY = packed record
  @{$ifdef __BYTES_BIG_ENDIAN__@}
  Fill: Integer (BitSizeOf (Word) - 16);
  Y, X: Word (8)
  @{$else@}
  X, Y: Word (8);
  Fill: Integer (BitSizeOf (Word) - 16)
  @{$endif@}
end;
@end smallexample

@cindex debug flag
El flag @samp{DEBUG} sebería ser usado para (y sólo para) ayudar en el debugueo,
ej. código que no cambia la funcionalidad real. Los programas deben compilar
con y sin poner @samp{DEBUG}. Lo último puede ejecutarse más lentamente y puede
producir mensajes adicionales útiles de una forma determinada, ej. claramente
marcados como mensajes de debugueo, por ejemplo prefijados con @samp{DEBUG: }, y
@emph{pueden} abortar la ejecución cuando detectan condiciones erróneas o dudosas.

@cindex condicionales y versiones diferentes
Los condicionales pueden ser usados para hacer versiones diferentes de algún código,
por ejemplo, usando números GMP si una condición se satisface y usando
enteros normales o reales en otro caso (GMP es una biblioteca para trabajar
con números muy grandes). En este caso, el nombre y significado de todas esas
definiciones usadas en un fichero deben ser explicados en un comentario cerca de la
parte superior. (Para eemplos, vea @samp{__BP_TYPE_SIZES__}, @samp{__BP_RANDOM__} y
@samp{__BP_PARAMSTR_0__} en la unidad System.) El código debe compilar con cualquier
combinación de ese conjunto de condicionales, lo cual significa que debe comprobar
exponencialente muchos casos -- aquí está una buena razón para mantener su número
tan pequeño como sea posible.

@cindex condicionales e implementaciones diferentes
Otro uso similar de los condicionales es para seleccionar entre diferentes
implementaciones No debería adoptar esta estrategia @emph{únicamente} si todas
las implementaciones están realmente soportadas o planeadas para ser soportadas.
De otra forma, sería mejor mover las implementaciones antiguas a su ``museo'' y
mantener el código limpio. Las notas acerca de la compilación de código de la regla
anterior se aplica aquí también.

@cindex condicionales complicados
Cuando necesite tratar con condicionales complicados, utilice sintaxis Pascal,
i.e. formatee los condicionales de acuerdocon las reglas para código Pascal, en vez de
sintaxis C. Este es un ejemplo tonto:

@smallexample
@{$if defined (Foo) or False@}
@end smallexample

En su lugar, este es un ejemplo que no debe seguir:

@smallexample
@{$if defined (Foo) || 0@}
@end smallexample

O incluso peor:

@smallexample
#if defined (Foo) || 0
@end smallexample

@cindex comentando código
Un condicional especial puede usarse para comentar código temporalmente.
Aquí está la sintaxis apropiada:

@smallexample
@{$if False@} @dots{} @{$endif@}
@end smallexample

@cindex condicionales y la versión de GPC
Una sentencia condicional estándar debería usarse en programas o unidades o módulos
que distribuya para asegurarse que la versión apropiada del Compilador Pascal GNU
se usa. Puede segui esta plantilla:

@smallexample
@{$if __GPC_RELEASE__ < 20020510@}
@{$error This unit requires GPC release 20020510 or newer.@}
@{$endif@}
@end smallexample

@node Espaciado
@section Cómo se usa el espaciado en el código

En general, no deberían usarse espacios múltiples excepto para el sangrado
y como se indica abajo

Un solo espacio va antes y despues de operadores, y  @samp{:=} y
@samp{..} así como @samp{:} en  @samp{Write}, @samp{WriteLn} y
@samp{WriteStr}; destués de la coma y otros @samp{:}. Este ejemplo debería
dejarlo claro:

@smallexample
var
  Foo: Integer;
  @dots{}
begin
  Foo := 42;
  WriteLn (Foo + 3 : 5, ' bar')
end;
@end smallexample

Ningún espacio debería ir antes del @samp{-} unario. De hecho, estas son
las formas correctas: @samp{x - 1}, @samp{-x}, @samp{-1}.

un espacio debe ir antes del paréntesis de apertura (@samp{(}) y después del
paréntesis de cierre (@samp{)}), excepto que sea adjacente a más paréntesis,
corchetes, @samp{^}, @samp{;}, @samp{,}. En otras palabras, un espacio va entre
identificadores o palabras reservadas y el paréntesis de apertura (@samp{(}).
(Todos los otros espacios en este ejempo son implicados ya por la regla previa.)
Vea:

@smallexample
Foo (Bar^(Baz[Qux * (i + 2)]), Fred (i) + 3);
@end smallexample

Para indexar arrays no use un espacio antes del corchete de apertura, ej:
@samp{Foo [42]} en vez de  @samp{Foo[42]}. Sin embargo, inserte un espacio
antes del corchete de apertura en las declaraciones de arrays, como:

@smallexample
Foo: array [1 .. 42] of Integer;
@end smallexample

Un espacio va antes del corchete de apertura de un constructor de conjuntos
en algunas situaciones -- esos corchetes deberían tratarse como paréntesis,
a diferencia de los corchetes usados en la indexación de un array.
Por ejemplo:

@smallexample
x := [0, 2 .. n];
@end smallexample

Pero:

@smallexample
Foo ([1, 2, 3]);
@end smallexample

Sin espacios para  @samp{.} and @samp{^}:

@smallexample
Rec.List^.Next^.Field := Foo
@end smallexample

Como ya apuntamos, un único espacio va después del brazo de apertura y antes del
brazo de cierre en los comentarios, pero no en las directivas del compilador. Además,
y ya dijimos esto en algún otro lugar del manual, dos espacios van antes de los
comentarios después de una línea de código. Por ejemplo:

@smallexample
Inc (x);  @{ Incrementa x. @}
@end smallexample

@cindex tabulación del código, espaciado
@cindex espaciado, tabulación del código
Opcionalmente use espacios adicionales para  ``tabular'' código. En nuestra
opinión, esto incrementa la legibilidad un montón, porque el ojo humano y el cerebro
están entrenados para reconocer estas estructuras, y similaridades y diferencias
entre las líneas pueden ser vistas más fácilmente, y cuando cambia el código,
es más fácil encontrar lugares relacionados. una aplicación de este principio
puede verse en las declaraciones ``interface'' (no tan aplicables cuando están
separadas por comentarios, pero, por ejemplo, cuando se se describen por un
comentario compartido sobre todas ellas):

@smallexample
function Pos             (const SubString, s: String): Integer;
function LastPos         (const SubString, s: String): Integer;
function PosCase         (const SubString, s: String): Integer;
function LastPosCase     (const SubString, s: String): Integer;
function CharPos         (const Chars: CharSet; const s: String): Integer;
function LastCharPos     (const Chars: CharSet; const s: String): Integer;
function PosFrom         (const SubString, s: String; From: Integer): Integer;
function LastPosTill     (const SubString, s: String; Till: Integer): Integer;
function PosFromCase     (const SubString, s: String; From: Integer): Integer;
function LastPosTillCase (const SubString, s: String; Till: Integer): Integer;
@end smallexample

También posible:

@smallexample
procedure Foo;
function  Bar @dots{};
procedure Baz;
@end smallexample

Y desde luego:

@smallexample
const
  FooBar = 1;
  Baz    = 2;
  Quux   = 3;
@end smallexample

La misma estrategia ``tabular'' usada en los interfaces y declaraciones const
puede usarse con los inicializadores:

@smallexample
const
  Foo: TBarArray =
    (('Foo'    ,  3),
     ('Bar baz', 42),
     (''       , -1));
@end smallexample

Y en sentencias @samp{case}:

@smallexample
case ReadKeyWord of
  kbLeft    : if s[n] > l    then Dec (s[n]) else s[n] := m[n];
  kbRight   : if s[n] < m[n] then Inc (s[n]) else s[n] := l;
  kbUp      : if n > 1 then Dec (n) else n := 5;
  kbDown    : if n < 5 then Inc (n) else n := 1;
  kbHome    : s[n] := l;
  kbEnd     : s[n] := m[n];
  kbPgUp,
  kbCtrlPgUp: n := 1;
  kbPgDn,
  kbCtrlPgDn: n := 5;
  kbCR      : Done := True;
end
@end smallexample

Y opcionalmente en otro código:

@smallexample
WriteCharAt (1, 1, 1,     Frame[1], TextAttr);
WriteCharAt (2, 1, w - 2, Frame[2], TextAttr);
WriteCharAt (w, 1, 1,     Frame[3], TextAttr);
@end smallexample

@node Rupturas de Línea
@section Dónde romper las líneas de código
@cindex rupturas de línea

Una ruptura de línea es opcional después de declaraciones @emph{locales} @samp{const},
@samp{type}, @samp{var} si contienen únicamente una sola declaración (pero es posible
tener múltiples identificadores en una única línea).

@smallexample
procedure Baz;
var Foo, Bar: Integer;
begin
  @dots{}
end;
@end smallexample

Desde luego, esto también se acepta:

@smallexample
procedure Baz;
var
  Foo, Bar: Integer;
begin
  @dots{}
end;
@end smallexample

Pero no siga este ejemplo:

@smallexample
procedure Baz;
var Foo, Bar: Integer;
    Qux: Real;
begin
  @dots{}
end;
@end smallexample

Si tiene muchas declaraciones puede romper las líneas de varias maneras. Lo siguiete
es la forma preferida para declaraciones @samp{var}:

@smallexample
var
  Foo, Bar, Baz, Qux, Quux, Corge, Grault, Garply, Waldo, Fred,
    Plugh, Xyzzy, Thud: Integer;
@end smallexample

o:

@smallexample
var
  Foo, Bar, Baz, Qux, Quux, Corge, Grault, Garply, Waldo: Integer;
  Fred, Plugh, Xyzzy, Thud: Integer;
@end smallexample

Esta última, sin embargo, es ma apropiada para campos de registros (@samp{record})
y para la parte pública de objetos (@samp{object}), especialmente si hay un
comentario para cada uno de ellos:


@smallexample
var
  Foo,
  Bar,
  Baz,
  Qux: Integer;
@end smallexample

No hay ruptura de línea después de declaraciones @samp{var} dentro de bloques de
sentencias, porque permiten sólo una declaración, y hacer una ruptura de línea podría
pareces como si se permitiera más de una.

@smallexample
Foo := Bar;
var Baz: array [1 .. Foo] of Integer;
@end smallexample

Como esto es una extensión de  GNU Pascal, use estas declaraciones muy de vez en
cuando, pero ejemplo para variables cuyo tamaño depende de valores computados
dentro de la rutina, o para variables dentro de los inicializadores o finalizadores
del módulo o unidad para evitar variables globales, aunque quizá piense usar una
subrutina.

@cindex especiado de etiquetas
No inserte una ruptura de línea después de @samp{label}. Esto es como se
deben declarar etiquetas:

@smallexample
label Foo, Bar, Baz;
@end smallexample

y como complemento, aquí está como no hacerlo:

@smallexample
label
  Foo,
  Bar,
  Baz;
@end smallexample

Algunas declaraciones en distintan líneas incluso no funcionan:

@smallexample
label
  Foo;
  Bar;
  Baz;
@end smallexample

@cindex case y ruptura de líneas
Aquí está un ejemplo de cómo usar rupturas de línea dentro de una sentencia case.

@smallexample
case
  foo:
    begin
      @dots{}
    end;
  bar,
  baz .. qux:
    @dots{}
  else
    @dots{}
end;
@end smallexample

O (``tabular''):

@smallexample
case
  foo:        begin
                @dots{}
              end;
  bar,
  baz .. qux: @dots{}
  else        @dots{}
end;
@end smallexample

@cindex romper líneas largas
Las sentencias largas o declaraciones deberían ser rotas en cualquier caso antes
de operadores o después de ellos (donde lo que se entiende por siempre es
al menos una subrutina) o después de una coma, con sangrado suficiente para
hacer el significado claro:

@c FIXME
@c
@c I don't think it's consistent to allow both before and after.

@smallexample
if (x = y)
   and (foo
        or (bar
            and (baz or qux))
        or fred) then
@end smallexample

or:

@smallexample
if (x = y) and
   (foo or
    (bar and
     (baz or qux)) or
    fred) then
@end smallexample

@cindex sentencias if then else y rupturas de línea
Aquí está como usar rupturas de línea dentro de sentencias. Otro uso
para ello es dónde debería usar una sentencia @samp{case} si fuera posible,
pero no es posible (por ejempo los typos no son ordinales, o los valores
a ser comparados no son constantes, o la comparación implica a una función
 (@samp{StrEqualCase}, o hay condiciones adicionales).

@smallexample
if @dots{} then
  a
else if @dots{} then
  b
else
  c
@end smallexample

Si  @samp{a} y no @samp{a} son casos principales, y @samp{b} y @samp{c}
son sub casos de no @samp{a}, utilice lo siguiente (la distinción quizá ser
cuastión de gustos a veces):

@smallexample
if @dots{} then
  a
else
  if @dots{} then
    b
  else
    c
@end smallexample

El ejemplo siguiente (biologicamente muy incompleto) contiene una mezcla de
ambas formas que consideramos razonable:

@smallexample
if Habitat = 'Water' then
  @{ Animals living in water @}
  WriteLn ('Is it a fish?')
else if Habitat = 'Air' then
  @{ Animals living in air @}
  WriteLn ('Is it a bird?')
else
  @{ Animals living on land @}
  if Legs = 8 then
    WriteLn ('Is it a spider?')
  else
    WriteLn ('Is it a gnu?')
@end smallexample

Los casos principales son determinados por el habitat, y el número de patas
determina algunos sub-casos.

@cindex bucles de control
Para bucles de control hay un breve resumen de posibilidades aquí:

@smallexample
for @dots{} do
  @dots{}
@end smallexample

@smallexample
while @dots{} do
  @dots{}
@end smallexample

@smallexample
repeat
  @dots{}
until @dots{}
@end smallexample

Si hay sóo una sentencia después de la cláusula @samp{if}, o en un
@samp{for} o bucle @samp{while}, o entre @samp{repeat} y
@samp{until}, y si esa orden es suficientemente corta, puede poner la
sntencia en una línea sola, coo esto:

@smallexample
if @dots{} then @dots{}
@end smallexample

@smallexample
for @dots{} do @dots{}
@end smallexample

@smallexample
while @dots{} do @dots{}
@end smallexample

@smallexample
repeat @dots{} until @dots{}
@end smallexample

Aquí está cómo comportarse cuando @samp{begin} yd @samp{end} están implicados.

@smallexample
if @dots{} then
  begin
    @dots{}
  end
@end smallexample

@smallexample
for @dots{} do
  begin
    @dots{}
  end
@end smallexample

@smallexample
while @dots{} do
  begin
    @dots{}
  end
@end smallexample

@cindex sangrado
El sangrado es de 2 caracteres de ancho, para cada @samp{begin},
@samp{then}, @samp{else}, @samp{case}, @samp{do} (@samp{for},
@samp{while}, @samp{with}, @samp{to begin}, @samp{to end}),
@samp{repeat}, @samp{record}, @samp{object}, @samp{type},
@samp{const}, @samp{var}, @samp{label}.

Los cuerpos y variables locales etc. de rutinas globalesno deben ser sangrados,
de la misma forma que las variables globales etc. Cada subrutina (cabecera y cuerpo)
y sus declaraciones, al contrario, deben ser sangradas.

@smallexample
program Prog;

var
  GlobalVar: Integer;

procedure GlobalProc;
var LocalVar: Integer;

  procedure LocalProc;
  var LocalLocalVar: Integer;
  begin
    WriteLn ('This is a local procedure.')
  end;

begin
  WriteLn ('This is a global procedure.')
end;

begin
  WriteLn ('This is the main program.')
end.
@end smallexample

Los registros variantes deberían ser sangrados como los siguientes:

@smallexample
type
  Foo = record
    NonVariant: Foo;
  case Discriminant: Bar of
    Val1: (Variant1: Baz;
           Variant2: Qux);
    Val2: (Variant3: Fred)
  end;

var
  Foo: record
    [ as above ]
  end = [ initializer ]
@end smallexample

Sangrados más grandes, ej. más de 2 caracteres de ancho, pueden usarse para romper
sentencias o declaraciones o para obtener código ``tabulado''.

Los condicionales  (@samp{@{$ifdef@}}) deberían estar al mismo nivel de sangrado que
el código al que afectan:

@smallexample
begin
  @{$ifdef DEBUG@}
  WriteLn ('Debugging version');
  @{$endif@}
  @dots{}
end;
@end smallexample

Los condicionales cortos que afectan sólo a una expresión pueden escribirse
dentro de una sola línea:

@smallexample
Foo := @{$ifdef DEBUG@} 'debug' @{$else@} 'release' @{$endif@};
@end smallexample

Si son usados intencionalmente en una forma contraria a las reglas sintácticas usuales,
póngalos donde parezcan quedar mejo y escriba un comentario:

@smallexample
begin
  @{ Do the code unconditionally if debugging @}
  @{$ifndef DEBUG@}
  if SomeCondition then
  @{$endif@}
    begin
      @dots{}
    end
end;
@end smallexample

La mayoría de las veces encontrará una forma más bonita y no menos
eficiente de escribir las mismas sentencias. En este caso, puede
hacerse de esta forma:

@smallexample
begin
  if @{$ifdef DEBUG@} True @{$else@} SomeCondition @{$endif@} then
    begin
      @dots{}
    end
end;
@end smallexample

O mucho mejor:

@smallexample
@{ globally @}
const
  DebugFlag = @{$ifdef DEBUG@} True @{$else@} False @{$endif@};

begin
  if DebugFlag or SomeCondition then
    begin
      @dots{}
    end
end;
@end smallexample

@node Cadenas
@section Cadenas
@cindex cadenas

La mayoría de las  reglas que hemos cubierto no se aplican alas cadenas. En general,
los mensajes contenidos en cadenas deberían seguir los Estándares de Codificación GNU,
por ejemplo, ponga los nombres entrecomillados dentro de  @samp{`} y @samp{'},
aunque esto significa que debe doblar el @samp{'} en una cadena Pascal.
@xref{Errores, , , estándares}, para más información.

Normalmente debería usar cadenas encerradas en comillas simples, como
@samp{'esta cadena que está leyendo'}. Utilice cadenas en dobles comillas
cuando necesite secuencias de escape tipo C como  @samp{"\t"}. Note
que @samp{NewLine} (@samp{"\n"}) está predefinido, así que usar @samp{NewLine}
es preferible a no ser que tenga que usar una cadena del estilo de C por otros
propositos.

Puede usar cadenas multilinea como la siguiente:

@smallexample
WriteLn ('Hello
world')
@end smallexample

o (quizá preferible, especialmente si el texto en la cadena contiene parágrafos
y/o sangrado dentro de ella misma):

@smallexample
WriteLn (
'Hello
world')
@end smallexample

Sin embargo, es posible también usar:

@smallexample
WriteLn ('Hello' + NewLine + 'world')
@end smallexample

(Note que el ejemplo anterior no compilará sin usar la unidad @code{GPC}.)

O, por supuesto:

@smallexample
WriteLn ('Hello');
WriteLn ('world')
@end smallexample

Cuando quiera verificar si una cadena está vacía, use esta sintaxis:

@smallexample
if s = '' then
  @dots{}
@end smallexample

El Compilador Pascal de GNU eventualmente lo optimizará eventualmente a la siguiente
prueba más eficiente, así que puede usar la anterior, más corta sin perjuicio:

@smallexample
if Length (s) = 0 then
  @dots{}
@end smallexample

Lo mismo se aplica para @samp{<>}, desde luego, e incluso para asignaciones donde
@samp{s := ''} es la forma recomendada y será optimizada por GPC a
@samp{SetLength (s, 0)}.

@node Internationalización
@section Técnicas de internacionalización
@cindex internationalización

Vea el manual de @samp{gettext} para información acerca de
internacionalización y localización.

Hay un proyecto en marcha por Eike Lange (@samp{eike(at)g-n-u.de})
que pretende proporcionar rutinas de internationalización para GNU Pascal
Puede obtener el fuente en tarball desde
@uref{http://www.gnu-pascal.de/contrib/eike/}.

Además de la unidad de internacionalización, puede encontrar otro paquete
que contiena una herramienta llamada  @code{pas2po}, usada para extraer cadenas
desde los fuentes de GNU Pascal  ej.. similarmente a lo que  @code{xgettext} hace
para los fuentes C y C++. @code{pas2po} no es tan cómodo como @code{xgettext}, pero
el programa está todavía en desarrollo. Por favor lea la documentación incluida con
el tarball y manténgase al tanto.

@node MemoryMap
@section MemoryMap
@findex MemoryMap

Esta sección de los Estándares de Codificación GNU  también se aplica a GNU Pascal.
Recuerde que @samp{mmap} actualmente significa @samp{MemoryMap} e
este contexto. @xref{Mmap, , , estándares}.

@node Documentación
@chapter Documentaci de Programas
@cindex documentación

Recomendamos leer la sección respectiva en los Estándares de Codificación GNU,
todo ello es aplicable a este contexto, también.  @xref{Documentación, , ,
estándares}. Éstas son algunas notas acerca de la escritura.

En lo que concierne a las páginas man, sería bueno tener una página man refiriéndose
a la documentación Info. Hay un programa GNU, llamado @samp{help2man}, que
genera una página man basada en la salida  @samp{--help} de un programa. Funciona bien,
excepto que siempre escribe @samp{FSF} que no es correcto para todos los
programas compilados con el Compilador Pascal de GNU, pero la salida puede
cambiarse fácilmente (por ejemplo, automáticamente usando @samp{sed}).

Sin embargo, no ponga mucho esfuerzo en las páginas man. Puede ser posible en un
principio, pero mantenerlas actualizadas junto con los fichero Texinfo significa
mucho trabajo. Encima de ésto, si no las mantiene actualizadas le van a causar más
confusión que ayuda.

Por un lado, si las páginas man se acortan mucho, van a perder información importante.
Por el otro, si no se acortan, son difíciles de navegar.

En otras palabras, sea devoto de la documentación Info (i.e., Texinfo).

@node Gestión de Liberaciones
@chapter El Proceso de Liberación
@cindex liberar

Por favor, lea el capítulo respectivo en los estándares de Codificación
GNU. Note que el esfuerzod e herramientas automatizadas de C no es necesario para los
programas Pascal normales. Además los Makefiles son a menudo innecesarios en GNU
Pascal. @xref{Gestión de Liberaciones, , , estándares}.

@menu
* Convenios en los Makefiles::           Convenios en los Makefiles
@end menu

@node Convenios en los Makefiles
@section Convenios en los Makefiles
@cindex convenios en los makefiles

Para sus proyectos Pascal no necesita probablemente grandes @samp{Makefile}s
y no necesita usar @samp{autoconf} o @samp{automake}. Puede darle  @samp{--automake}
al Compilador Pascal de GNU así que él se hace cargo de las dependencias
por usted. (Cuando esto se estaba escribiendo la característica @samp{automake} del
Compilador de Pascal de GNU tiene algunos fallos pequeños, pero serán corregidos.
También, hay planeada una utilidad llamada @samp{gp}, que está en desarrollo ahora,
que simplificará el proceso de compilación mucho más. En cualquier caso no necesita
escribir complejos @samp{Makefile}s usted mismo.)

Un Makefile @emph{sencillo} podría ser como:

@smallexample
GPC_FLAGS=-O2

all: foo

foo: foo.pas unit1.pas
     gpc --automake $(GPC_FLAGS) foo.pas

mostlyclean:
     -rm -f *.o *.gpi *.gpm core

clean: mostlyclean
      -rm -f foo

distclean: clean

extraclean: distclean
      -rm -f *~*

maintainer-clean: extraclean
@end smallexample

Quizá, sin embargo, quiera poner otras reglas en un @samp{Makefile} para
construir documentación, ficheros de datos, hacer distribuciones o lo que sea.
Este tipo de cosas están fuera del ámbito de este texto. Puede normalmente
hacer las compilaciones Pascal con una sola llamada  @samp{gpc --automake} por
programa.

@node Glosario
@chapter Glosario de palabras usadas a través de este texto
@cindex glosario

Rutinas son  @samp{procedure}s, @samp{function}s,
@samp{constructor}s, @samp{destructor}s u operadores (definidos por el usuario).

Declaraciones son aquellas partes de un programa que ``anuncian'' la existencia de
propiedades de ciertos objetos como constantes , tipos, variables, rutinas, unidades,
módulos y el programa.

Sentencias son aquellas partes de un programa que ``hacen'' algo. Una sentencia simple
es una asignación, una llamada a procedimiento, una sentencia de salto  (@samp{goto},
@samp{Exit}, @samp{Return}, @samp{Break}, @samp{Continue}), una sentencia en ensamblador,
o una sentencia compuesta  (@samp{begin} @dots{} @samp{end}, @samp{if},
@samp{case}, @samp{repeat}, @samp{while}, @samp{for}, @samp{with}) que en cambio puede
contener una o varias sentencias.

Identificadore son aquellos elementos del lenguaje que dan nombres a objetos
como rutinas, constantes, tipos, variables, unidades, módulos. Pueden ser
redefinidos localmente, excepto las palabras clave que son parte de las
construcciones sintácticas fijas (por ejemplo @samp{if} @dots{}
@samp{then} @dots{} @samp{else}) y no pueden ser redefinidas. Las macros
no son elementos del lenguaje debido a que son expandidas por el preprocesador
y nunca son vistas por el compilador.

Endianidad significa el orden en que los bytes de un valor más
grande que un byte se almacenan en memoria.  Esto afecta, por
ejemplo, a los valores enteros, y punteros mientras que los arrays
de caracteres de un sólo byte no están afectados.
(@pxref{Endianidad, , , gpc})

@emph{Nota:} Otros items serán incluidos aquí cuando parezca útil.
Si quiere una definición de algún otro término, díganoslo.

@node Índice
@unnumbered Indice
@printindex cp

@contents

@bye
