<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 

    "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd" [

<!ENTITY Emacs "<application>Emacs</application>">

<!ENTITY Vim "<application>Vim</application>">

<!ENTITY ChangeLog "<filename>ChangeLog</filename>">

]>

<article class="techreport" id="index" lang="es">

  <articleinfo>

    <title>Guía de programación de GNOME</title>

    <authorgroup>

      <author>

	<firstname>Federico</firstname>

	<surname>Mena Quintero</surname>

	<affiliation>

	  <address>

	    <email>federico@gnu.org</email>

	  </address>

	</affiliation>

      </author>

      <author>

	<firstname>Miguel</firstname>

	<surname>de Icaza</surname>

	<affiliation>

	  <address>

	    <email>miguel@kernel.org</email>

	  </address>

	</affiliation>

      </author>

      <author>

	<firstname>Morten</firstname>

	<surname>Welinder</surname>

	<affiliation>

	  <address>

	    <email>terra@diku.dk</email>

	  </address>

	</affiliation>

      </author>

      <othercredit>

	<firstname>Germ&aacute;n</firstname>

	<surname>Po&oacute; Caama&ntilde;o</surname>

	<contrib>Traducción al español</contrib>

	<affiliation>

	  <address>

	    <email>gpoo@ubiobio.cl</email>

	  </address>

	</affiliation>

      </othercredit>

      <othercredit>

	<firstname>Lucas</firstname>

	<surname>Vieites Fari&ntilde;a</surname>

	<contrib>Revisión de la traducción al español</contrib>

	<affiliation>

	  <address>

	    <email>lucas@asixinformatica.com</email>

	  </address>

	</affiliation>

      </othercredit>

    </authorgroup>

    <copyright>

      <year>2000</year>

      <holder>The Free Software Foundation</holder>

    </copyright>

    <copyright>

      <year>2004&mdash;2006</year>

      <holder>GNOME Foundation, respecto de la versión en español.</holder>

    </copyright>

    <abstract>

      <para>

	Este artículo contiene varías guías y sugerencias para los

	programadores de GNOME, así como ciertas políticas que

	deberían seguirse cuando se escriben programas para GNOME.

	Es un intento para que los programadores puedan aprender

	acerca del proceso de desarrollo de GNOME y su filosofía.

	GNOME es un esfuerzo de equipo, así que será útil para 

	que los programadores sepan «la forma de hacer la

	cosas».

      </para>

    </abstract>

  </articleinfo>

  <!-- Introduction -->

  <sect1 id="intro">

    <title>Introducción</title>

    <para>

	  GTK+, la biblioteca de interfaz de usuario básica de GNOME, nos

	  ha enseñado algunas lecciones importantes en el diseño de software.

	  El código de GTK+ es limpio, consistente, mantenible y tiene

	  sentido.  Tal código no sólo provoca placer al trabajar con el,

	  sino que además es un incentivo para las buenas prácticas de 

	  programación para aquellos que quieran extenderlo y modificarlo.

    </para>

    <para>

	  En este artículo intentamos presentar algunas sugerencias y 

	  lineamientos que deberías tener en cuenta cuando escribas código

	  para el proyecto GNOME.  Presentamos algunas de las políticas

	  que deben seguirse cuando se modifica el código de otras

	  personas, usando el repositorio CVS y asegurándose de que el

	  código se ajusta para ser incluído en GNOME. También 

	  presentamos información que será útil para los mantenedores

	  de paquetes.

    </para>

    <para>

	  Además de este documento, asegúrate de leer los Estándares de 

	  Programación de GNU.  Estos se encuentran disponibles en el

	  nodo info <filename>(Standards)</filename> en la documentación

	  estándar de GNU.

    </para>

  </sect1>

  <!-- The Importance of Writing Good Code -->

  <sect1 id="good-code">

    <title>La importancia de escribir buen código</title>

    <para>

	  GNOME es un proyecto de software libre muy ambicioso y, como tal,

	  está compuesto por muchos paquetes de software que son más o menos

	  independientes el uno del otro.  Mucho del trabajo en GNOME lo 

	  realizan voluntarios; programadores que vienen y se van

	  en cualquier momento y que serán capaces de dedicar

	  diferentes cantidades de tiempo al proyecto GNOME.

	  Muchas personas trabajan en software libre en su tiempo libre o

	  como un pasatiempo, así, si sus responsabilidades del ‘mundo

	  real’ cambian, se verá reflejado en la cantidad de trabajo que

	  dedicarán a proyectos de software libre.

    </para>

    <para>

	  Se tarda mucho tiempo en escribir software y supone una

	  gran cantidad de trabajo. Es por esto que muchos

	  de los voluntarios de tiempo parcial no pueden comenzar 

	  grandes proyectos por sí mismos; es mucho más fácil y

	  gratificante contribuir a proyectos existentes, puesto que

	  los resultados son inmediatamente visibles y usables.

    </para>

    <para>

	  Teniendo esto en cuenta y el hecho que los programadores de

	  software libre tiene recursos escasos, concluimos que

	  para los proyectos existentes es muy importante facilitar,

	  tanto como sea posible, que otras personas puedan contribuir.

	  Una forma de hacerlo es asegurándose de que los programas

	  sean fáciles de leer, entender y modificar.

    </para>

    <para>

	  El código desordenado es difícil de leer y las personas pueden

	  perder interés si no son capaces de descifrar lo que el código

	  intenta hacer.  Además, es importante que los programadores sean

	  capaces de entender el código rápidamente, y así poder comenzar

	  a contribuir reparando fallos y extendiéndolo en un período breve

	  de tiempo.  El código fuente es una forma de comunicación, y así

	  como a alguien podría no querer leer una novela con errores

	  ortográficos y mala puntuación, los programadores deben intentar

	  escribir buen código de tal forma que sea fácil de entender y

	  modificar por otros.

    </para>

    <para>

	  Existen algunas cualidades que son importantes en un buen 

	  código y por qué son importantes para los desarrolladores

	  de software libre:

      <variablelist>

	<varlistentry>

	  <term>Limpieza</term>

	  <listitem>

	    <para>

		  Un código limpio es fácil de leer; permite a las

		  personas leerlo con un mínimo esfuerzo y así pueden

		  entenderlo más fácilmente.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term>Consistencia</term>

	  <listitem>

	    <para>

		  El código consistente permite más fácilmente que las

		  personas entiendan como funciona el programa; cuando se

		  lee código consistente, subconcientemente uno se forma

		  un número de supuestos y expectativas acerca del 

		  funcionamiento del código, de esta forma es más fácil

		  y seguro realizarle modificaciones.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term>Extensibilidad</term>

	  <listitem>

	    <para>

		  El código de propósito general es más fácil de reutilizar

		  y modificar que el código demasiado específico con muchos

		  supuestos escritos directamente en el código (hardcoded).

		  Cuando alguien desea agregar una nueva característica

		  a un programa, obviamente será más fácil hacerlo si el

		  código fue diseñado para ser extensible desde el inicio.

		  El código que no fue escrito de esta forma hará que las

		  personas deban implementar hacks muy feos para poder

		  añadir características.

	    </para>

	  </listitem>

	</varlistentry>

	<varlistentry>

	  <term>Corrección</term>

	  <listitem>

	    <para>

		  Finalmente, el código diseñado debe ser correcto para

		  que las personas pierdan menos tiempo preocupándose de

		  los errores y se ocupen  en extender las

		  características de un programa.  Los usuarios también

		  apreciarán un código correcto, ya que a nadie le gusta

		  que un programa se caiga.

	    </para>

	  </listitem>

	</varlistentry>

      </variablelist>

    </para>

    <para>

	  En resumen, los programadores a menudo contribuyen en

	  su tiempo libre a proyectos de software libre, y aún quienes

	  contribuyen de forma regular pueden detenerse en cualquier

	  instante del tiempo, así que es muy importante que el código

	  sea bueno y les permita modificarlo facilmente.  El resultado

	  final será un mejor software al que los programadores 

	  querrán extender.

    </para>

  </sect1>

  <!-- Coding Style -->

  <sect1 id="code-style">

    <title>Estilo de programación</title>

    <para>

      ‘El estilo de programación’ se refiere a la forma en 

	  que se da formato al código fuente.  Para C, esto involucra

	  la forma en que se ubican las llaves, se indenta el código y

	  se utilizan los paréntesis.  GNOME tiene una mezcla de estilos

	  de programación y no se obliga el uso de ninguno de ellos.  Lo más

	  importante es que el código sea consistente dentro de un programa

	  o una biblioteca — el código con un formato desordenado

	  no es aceptable debido a que es difícil de leer.

    </para>

    <para>

	  Cuando escribas un nuevo programa o biblioteca, sigue un

	  estilo consistente de ubicación de llaves y de indentación.

	  Si no tienes ninguna preferencia personal de estilo, 

	  recomendamos el estilo de programación del núcleo de Linux o

	  el estilo de programación de GNU.

    </para>

    <para>

	  Lee el nodo de info <filename>(Standards)Writing C</filename> 

	  en la documentación de GNU. Luego, obtén el código fuente

	  de Linux y lee el archivo 

	  <filename>linux/Documentation/CodingStyle</filename>, e

	  ignora los chistes de Linus.  Estos dos documentos te darán

	  una buena idea de nuestras recomendaciones para el código de

	  GNOME.

    </para>

    <!-- Indentation Style -->

    <sect2 id="indent">

      <title>Estilo de indentación</title>

      <para>

		Para el código del núcleo de GNOME preferimos el estilo

		de indentación del núcleo de Linux.  Usa tabuladores

		de 8 espacios para la indentación.

      </para>

      <para>

		Usar tabuladores de 8 espacios para indentación proporciona

		un número de beneficios.  Permite que el código sea más

		fácil de leer, ya que la indentación se marca claramente.

		También ayuda a mantener el código ordenado

		forzando a dividir funciones en trozos más modulares y

		bien definidos — si la indentación va más allá del

		margen derecho, significa que la función está mal

		diseñada y que debiera dividirse para hacerla más modular

		o bien, repensarla.

      </para>

      <para>

		Los tabuladores de 8 espacios para indentación también

		ayudan al diseño de funciones que encajen bien en la pantalla, 

		lo cual significa que las personas puedan entender el código

		sin tener que desplazarse atrás y adelante para entenderlo.

      </para>

      <para>

		Si usas &Emacs;, entonces puedes seleccionar el estilo de

		indentación del núcleo de Linux incluyendo en el 

		archivo <filename>.emacs</filename> lo siguiente:

	<programlisting>

(add-hook 'c-mode-common-hook

          (lambda ()

            (c-set-style "k&r")

            (setq c-basic-offset 8)))</programlisting>

	En los nuevos Emacs o con el nuevo cc-mode, puedes ser capaz

	de hacerlo más simple con:

	<programlisting>

(add-hook 'c-mode-common-hook

          (lambda ()

            (c-set-style "linux")))</programlisting>

      </para>

      <para>

		El estilo de indentación de GNU es el predeterminado para

		&Emacs;, así que no es necesario agregar nada en el 

		archivo <filename>.emacs</filename> para habilitarlo.

		Si deseas seleccionarlo explícitamente, sustituye

		«gnu» por «linux» en el ejemplo anterior.

      </para>

      <para>

		Si usas &Vim;, entonces puedes seleccionar el estilo

		de indentación del núcleo de Linux incluyendo el 

		siguiente fragmento en el archivo 

		<filename>.vimrc</filename>:

	<programlisting>

set ts=8

if !exists("autocommands_loaded")

  let autocommands_loaded = 1

  augroup C

      autocmd BufRead *.c set cindent

  augroup END

endif</programlisting>

      </para>

      <para>

		Como alternativa puedes seleccionar el estilo de 

		indentación de GNU en &Vim; usando lo siguiente en

		el archivo <filename>.vimrc</filename>:

	<footnote>

	  <para>

	    Gracias a Tomas Ögren por proporcionar este código.

	  </para>

	</footnote>:

	<programlisting>

augroup C

   autocmd BufRead *.c set cinoptions={.5s,:.5s,+.5s,t0,g0,^-2,e-2,n-2,p2s,(0,=.5s formatoptions=croql cindent shiftwidth=4 tabstop=8

augroup END</programlisting>

      </para>

      <note>

	<para>

	  Si sabe personalizar el estilo de indentación en otros

	  editores populares, por favor háganoslo saber y así podemos

	  expandir este documento.

	</para>

      </note>

    </sect2>

    <!-- Naming Conventions -->

    <sect2 id="naming">

      <title>Convenciones de nombres</title>

      <para>

		Es importante seguir una buena convención de nombres para

		los símbolos de los programas.   Es específicamente 

		importante para las bibliotecas, ya que no debería

		ensuciarse el espacio de nombres global — es muy

		molesto cuando una biblioteca tiene símbolos nombrados

		desordenadamente que chocan con nombres que pueda

		querer usar en sus programas.

      </para>

      <para>

		Los nombres de las funciones deberían ser de la forma

		<function>modulo_submodulo_operacion</function>, por ejemplo,

		<function>gnome_canvas_set_scroll_region</function> o

		<function>gnome_mime_get_keys</function>.  Esta convención

		elimina las colisiones de nombres de símbolos entre módulos.

		Es muy importante para las bibliotecas.

      </para>

      <para>

		Los símbolos deben tener nombres descriptivos.  Como Linus

		dice, no use <function>cntusr()</function>, sino que use

		<function>count_active_users()</function>.  Esto permite

		que el código sea más fácil de leer y casi se auto

		documenta.

      </para>

      <para>

		Intente usar las mismas convenciones de nombre que tienen

		GTK+ y las bibliotecas de GNOME:

	<itemizedlist>

	  <listitem>

	    <para>

		  Los nombres de las funciones en minúsculas, con líneas

		  de subrayado para separar palabras, tal como:

	      <function>gnome_canvas_set_scroll_region()</function>,

	      <function>gnome_mime_get_keys()</function>.

	    </para>

	  </listitem>

	  <listitem>

	    <para>

		  Las macros y las enumeraciones en mayúsculas, con líneas

		  de subrayado para separar palabras, tal como:

	      <symbol>GNOMEUIINFO_SUBTREE()</symbol> para una macro y

	      <symbol>GNOME_INTERACT_NONE</symbol> para un valor 

		  enumerado.

	    </para>

	  </listitem>

	  <listitem>

	    <para>

		  Los nombres de tipos y estructuras usan una mezcla de

		  mayúsculas y minúsculas, tal como:

	      <symbol>GnomeCanvasItem</symbol>,

		  <symbol>GnomeIconList</symbol>.

	    </para>

	  </listitem>

	</itemizedlist>

	Al utilizar líneas de subrayado para separar palabras el

	código estará menos apretado y facilita la edición, ya

	que puede usar las secuencias de teclas que permiten

	navegar entre palabras más rápidamente en cualquier editor.

      </para>

      <para>

		Si estás escribiendo una biblioteca, entonces puedes necesitar

		exportar símbolos que serán usados sólo dentro de la

		biblioteca.   Por ejemplo, dos de los archivos objeto que

		componen la biblioteca <filename>libfoo.so</filename> pueden

		requerir acceder a símbolos ubicados en el otro archivo,

		pero se tiene la intención que éstos símbolos sean 

		utilizados desde los programas de usuario.  En este caso,

		coloca una línea de subrayado antes del nombre de la

		función y haz que la primera palabra siga la convención

		estándar módulo/submódulo.  Por ejemplo, podrías tener

		una función llamada

	<function>_foo_internal_frobnicate()</function>.

      </para>

      <!-- Consistency in Naming -->

      <sect3 id="consist">

	<title>Consistencia entre nombres</title>

	<para>

	  Es importante que las variables se nombren de manera 

	  consistente.  Por ejemplo, un módulo que manipula una

	  lista puedes elegir nombrar las variables que mantienen

	  un puntero a la lista como «<symbol>l</symbol>», 

	  por elegancia y simplicidad.  Sin embargo, es importante que

	  un módulo que manipula widgets y tamaños no use variables

	  llamadas «<symbol>w</symbol>» tanto para

	  widgets y anchos («width») (como en valores de ancho/alto);

	  esto podría hacer que el código sea inconsistente

	  y difícil de leer.

	</para>

	<para>

	  Por supuesto, nombre muy cortos y elegantes solamente deberían

	  ser usados para variables locales de funciones.

	  Nunca llame una variable global «<symbol>x</symbol>»; use 

	  un nombre más largo que indique lo que significa.

	</para>

      </sect3>

    </sect2>

    <!-- Cleanliness -->

    <sect2 id="clean">

      <title>Limpieza</title>

      <para>

		El código de GNOME debe ser tan limpio como sea posible.

		Esto implica usar un estilo de indentación consistente

		y una buena convención para nombrar símbolos, como se

		ha indicado anteriormente.  Esto también implica lo

		siguiente.

      </para>

      <para>

		Aprender el uso correcto de la palabra reservada

		<symbol>static</symbol>.

		<emphasis>No</emphasis> declarar todos los símbolos como

		globales.  Esto tiene la ventaja de poder usar nombres

		más cortos dentro de las funciones en un sólo archivo

		fuente, ya que no son globalmente visibles y por

		consiguiente no necesitas emplear el prefijo 

		módulo/submódulo.

      </para>

      <para>

		Aprender el uso correcto de la palabra reservada

		<symbol>const</symbol>.  Úsala consistentemente,

		así permitirás al compilador que atrape muchos

		errores estúpidos.

      </para>

      <para>