75 <year>2000</year> |
75 <year>2000</year> |
76 <holder>The Free Software Foundation</holder> |
76 <holder>The Free Software Foundation</holder> |
77 </copyright> |
77 </copyright> |
78 <copyright> |
78 <copyright> |
79 <year>2004—2006</year> |
79 <year>2004—2006</year> |
80 <holder>GNOME Foundation, respecto de la versión en español.</holder> |
80 <holder>GNOME Foundation, respecto de la versión en español.</holder> |
81 </copyright> |
81 </copyright> |
82 |
82 |
83 <abstract> |
83 <abstract> |
84 <para> |
84 <para> |
85 Este artículo contiene varías guías y sugerencias para los |
85 Este artÃculo contiene varÃas guÃas y sugerencias para los |
86 programadores de GNOME, así como ciertas políticas que |
86 programadores de GNOME, asà como ciertas polÃticas que |
87 deberían seguirse cuando se escriben programas para GNOME. |
87 deberÃan seguirse cuando se escriben programas para GNOME. |
88 Es un intento para que los programadores puedan aprender |
88 Es un intento para que los programadores puedan aprender |
89 acerca del proceso de desarrollo de GNOME y su filosofía. |
89 acerca del proceso de desarrollo de GNOME y su filosofÃa. |
90 GNOME es un esfuerzo de equipo, así que será útil para |
90 GNOME es un esfuerzo de equipo, asà que será útil para |
91 que los programadores sepan «la forma de hacer la |
91 que los programadores sepan «la forma de hacer la |
92 cosas». |
92 cosas». |
93 </para> |
93 </para> |
94 </abstract> |
94 </abstract> |
95 </articleinfo> |
95 </articleinfo> |
96 |
96 |
97 <!-- Introduction --> |
97 <!-- Introduction --> |
98 |
98 |
99 <sect1 id="intro"> |
99 <sect1 id="intro"> |
100 <title>Introducción</title> |
100 <title>Introducción</title> |
101 |
101 |
102 <para> |
102 <para> |
103 GTK+, la biblioteca de interfaz de usuario básica de GNOME, nos |
103 GTK+, la biblioteca de interfaz de usuario básica de GNOME, nos |
104 ha enseñado algunas lecciones importantes en el diseño de software. |
104 ha enseñado algunas lecciones importantes en el diseño de software. |
105 El código de GTK+ es limpio, consistente, mantenible y tiene |
105 El código de GTK+ es limpio, consistente, mantenible y tiene |
106 sentido. Tal código no sólo provoca placer al trabajar con el, |
106 sentido. Tal código no sólo provoca placer al trabajar con el, |
107 sino que además es un incentivo para las buenas prácticas de |
107 sino que además es un incentivo para las buenas prácticas de |
108 programación para aquellos que quieran extenderlo y modificarlo. |
108 programación para aquellos que quieran extenderlo y modificarlo. |
109 </para> |
109 </para> |
110 |
110 |
111 <para> |
111 <para> |
112 En este artículo intentamos presentar algunas sugerencias y |
112 En este artÃculo intentamos presentar algunas sugerencias y |
113 lineamientos que deberías tener en cuenta cuando escribas código |
113 lineamientos que deberÃas tener en cuenta cuando escribas código |
114 para el proyecto GNOME. Presentamos algunas de las políticas |
114 para el proyecto GNOME. Presentamos algunas de las polÃticas |
115 que deben seguirse cuando se modifica el código de otras |
115 que deben seguirse cuando se modifica el código de otras |
116 personas, usando el repositorio CVS y asegurándose de que el |
116 personas, usando el repositorio CVS y asegurándose de que el |
117 código se ajusta para ser incluído en GNOME. También |
117 código se ajusta para ser incluÃdo en GNOME. También |
118 presentamos información que será útil para los mantenedores |
118 presentamos información que será útil para los mantenedores |
119 de paquetes. |
119 de paquetes. |
120 </para> |
120 </para> |
121 |
121 |
122 <para> |
122 <para> |
123 Además de este documento, asegúrate de leer los Estándares de |
123 Además de este documento, asegúrate de leer los Estándares de |
124 Programación de GNU. Estos se encuentran disponibles en el |
124 Programación de GNU. Estos se encuentran disponibles en el |
125 nodo info <filename>(Standards)</filename> en la documentación |
125 nodo info <filename>(Standards)</filename> en la documentación |
126 estándar de GNU. |
126 estándar de GNU. |
127 </para> |
127 </para> |
128 </sect1> |
128 </sect1> |
129 |
129 |
130 <!-- The Importance of Writing Good Code --> |
130 <!-- The Importance of Writing Good Code --> |
131 |
131 |
132 <sect1 id="good-code"> |
132 <sect1 id="good-code"> |
133 <title>La importancia de escribir buen código</title> |
133 <title>La importancia de escribir buen código</title> |
134 |
134 |
135 <para> |
135 <para> |
136 GNOME es un proyecto de software libre muy ambicioso y, como tal, |
136 GNOME es un proyecto de software libre muy ambicioso y, como tal, |
137 está compuesto por muchos paquetes de software que son más o menos |
137 está compuesto por muchos paquetes de software que son más o menos |
138 independientes el uno del otro. Mucho del trabajo en GNOME lo |
138 independientes el uno del otro. Mucho del trabajo en GNOME lo |
139 realizan voluntarios; programadores que vienen y se van |
139 realizan voluntarios; programadores que vienen y se van |
140 en cualquier momento y que serán capaces de dedicar |
140 en cualquier momento y que serán capaces de dedicar |
141 diferentes cantidades de tiempo al proyecto GNOME. |
141 diferentes cantidades de tiempo al proyecto GNOME. |
142 Muchas personas trabajan en software libre en su tiempo libre o |
142 Muchas personas trabajan en software libre en su tiempo libre o |
143 como un pasatiempo, así, si sus responsabilidades del ‘mundo |
143 como un pasatiempo, asÃ, si sus responsabilidades del ‘mundo |
144 real’ cambian, se verá reflejado en la cantidad de trabajo que |
144 real’ cambian, se verá reflejado en la cantidad de trabajo que |
145 dedicarán a proyectos de software libre. |
145 dedicarán a proyectos de software libre. |
146 </para> |
146 </para> |
147 |
147 |
148 <para> |
148 <para> |
149 Se tarda mucho tiempo en escribir software y supone una |
149 Se tarda mucho tiempo en escribir software y supone una |
150 gran cantidad de trabajo. Es por esto que muchos |
150 gran cantidad de trabajo. Es por esto que muchos |
151 de los voluntarios de tiempo parcial no pueden comenzar |
151 de los voluntarios de tiempo parcial no pueden comenzar |
152 grandes proyectos por sí mismos; es mucho más fácil y |
152 grandes proyectos por sà mismos; es mucho más fácil y |
153 gratificante contribuir a proyectos existentes, puesto que |
153 gratificante contribuir a proyectos existentes, puesto que |
154 los resultados son inmediatamente visibles y usables. |
154 los resultados son inmediatamente visibles y usables. |
155 </para> |
155 </para> |
156 |
156 |
157 <para> |
157 <para> |
158 Teniendo esto en cuenta y el hecho que los programadores de |
158 Teniendo esto en cuenta y el hecho que los programadores de |
159 software libre tiene recursos escasos, concluimos que |
159 software libre tiene recursos escasos, concluimos que |
160 para los proyectos existentes es muy importante facilitar, |
160 para los proyectos existentes es muy importante facilitar, |
161 tanto como sea posible, que otras personas puedan contribuir. |
161 tanto como sea posible, que otras personas puedan contribuir. |
162 Una forma de hacerlo es asegurándose de que los programas |
162 Una forma de hacerlo es asegurándose de que los programas |
163 sean fáciles de leer, entender y modificar. |
163 sean fáciles de leer, entender y modificar. |
164 </para> |
164 </para> |
165 |
165 |
166 <para> |
166 <para> |
167 El código desordenado es difícil de leer y las personas pueden |
167 El código desordenado es difÃcil de leer y las personas pueden |
168 perder interés si no son capaces de descifrar lo que el código |
168 perder interés si no son capaces de descifrar lo que el código |
169 intenta hacer. Además, es importante que los programadores sean |
169 intenta hacer. Además, es importante que los programadores sean |
170 capaces de entender el código rápidamente, y así poder comenzar |
170 capaces de entender el código rápidamente, y asà poder comenzar |
171 a contribuir reparando fallos y extendiéndolo en un período breve |
171 a contribuir reparando fallos y extendiéndolo en un perÃodo breve |
172 de tiempo. El código fuente es una forma de comunicación, y así |
172 de tiempo. El código fuente es una forma de comunicación, y asà |
173 como a alguien podría no querer leer una novela con errores |
173 como a alguien podrÃa no querer leer una novela con errores |
174 ortográficos y mala puntuación, los programadores deben intentar |
174 ortográficos y mala puntuación, los programadores deben intentar |
175 escribir buen código de tal forma que sea fácil de entender y |
175 escribir buen código de tal forma que sea fácil de entender y |
176 modificar por otros. |
176 modificar por otros. |
177 </para> |
177 </para> |
178 |
178 |
179 <para> |
179 <para> |
180 Existen algunas cualidades que son importantes en un buen |
180 Existen algunas cualidades que son importantes en un buen |
181 código y por qué son importantes para los desarrolladores |
181 código y por qué son importantes para los desarrolladores |
182 de software libre: |
182 de software libre: |
183 |
183 |
184 <variablelist> |
184 <variablelist> |
185 <varlistentry> |
185 <varlistentry> |
186 <term>Limpieza</term> |
186 <term>Limpieza</term> |
187 <listitem> |
187 <listitem> |
188 <para> |
188 <para> |
189 Un código limpio es fácil de leer; permite a las |
189 Un código limpio es fácil de leer; permite a las |
190 personas leerlo con un mínimo esfuerzo y así pueden |
190 personas leerlo con un mÃnimo esfuerzo y asà pueden |
191 entenderlo más fácilmente. |
191 entenderlo más fácilmente. |
192 </para> |
192 </para> |
193 </listitem> |
193 </listitem> |
194 </varlistentry> |
194 </varlistentry> |
195 <varlistentry> |
195 <varlistentry> |
196 <term>Consistencia</term> |
196 <term>Consistencia</term> |
197 <listitem> |
197 <listitem> |
198 <para> |
198 <para> |
199 El código consistente permite más fácilmente que las |
199 El código consistente permite más fácilmente que las |
200 personas entiendan como funciona el programa; cuando se |
200 personas entiendan como funciona el programa; cuando se |
201 lee código consistente, subconcientemente uno se forma |
201 lee código consistente, subconcientemente uno se forma |
202 un número de supuestos y expectativas acerca del |
202 un número de supuestos y expectativas acerca del |
203 funcionamiento del código, de esta forma es más fácil |
203 funcionamiento del código, de esta forma es más fácil |
204 y seguro realizarle modificaciones. |
204 y seguro realizarle modificaciones. |
205 </para> |
205 </para> |
206 </listitem> |
206 </listitem> |
207 </varlistentry> |
207 </varlistentry> |
208 <varlistentry> |
208 <varlistentry> |
209 <term>Extensibilidad</term> |
209 <term>Extensibilidad</term> |
210 <listitem> |
210 <listitem> |
211 <para> |
211 <para> |
212 El código de propósito general es más fácil de reutilizar |
212 El código de propósito general es más fácil de reutilizar |
213 y modificar que el código demasiado específico con muchos |
213 y modificar que el código demasiado especÃfico con muchos |
214 supuestos escritos directamente en el código (hardcoded). |
214 supuestos escritos directamente en el código (hardcoded). |
215 Cuando alguien desea agregar una nueva característica |
215 Cuando alguien desea agregar una nueva caracterÃstica |
216 a un programa, obviamente será más fácil hacerlo si el |
216 a un programa, obviamente será más fácil hacerlo si el |
217 código fue diseñado para ser extensible desde el inicio. |
217 código fue diseñado para ser extensible desde el inicio. |
218 El código que no fue escrito de esta forma hará que las |
218 El código que no fue escrito de esta forma hará que las |
219 personas deban implementar hacks muy feos para poder |
219 personas deban implementar hacks muy feos para poder |
220 añadir características. |
220 añadir caracterÃsticas. |
221 </para> |
221 </para> |
222 </listitem> |
222 </listitem> |
223 </varlistentry> |
223 </varlistentry> |
224 <varlistentry> |
224 <varlistentry> |
225 <term>Corrección</term> |
225 <term>Corrección</term> |
226 <listitem> |
226 <listitem> |
227 <para> |
227 <para> |
228 Finalmente, el código diseñado debe ser correcto para |
228 Finalmente, el código diseñado debe ser correcto para |
229 que las personas pierdan menos tiempo preocupándose de |
229 que las personas pierdan menos tiempo preocupándose de |
230 los errores y se ocupen en extender las |
230 los errores y se ocupen en extender las |
231 características de un programa. Los usuarios también |
231 caracterÃsticas de un programa. Los usuarios también |
232 apreciarán un código correcto, ya que a nadie le gusta |
232 apreciarán un código correcto, ya que a nadie le gusta |
233 que un programa se caiga. |
233 que un programa se caiga. |
234 </para> |
234 </para> |
235 </listitem> |
235 </listitem> |
236 </varlistentry> |
236 </varlistentry> |
237 </variablelist> |
237 </variablelist> |
238 </para> |
238 </para> |
239 |
239 |
240 <para> |
240 <para> |
241 En resumen, los programadores a menudo contribuyen en |
241 En resumen, los programadores a menudo contribuyen en |
242 su tiempo libre a proyectos de software libre, y aún quienes |
242 su tiempo libre a proyectos de software libre, y aún quienes |
243 contribuyen de forma regular pueden detenerse en cualquier |
243 contribuyen de forma regular pueden detenerse en cualquier |
244 instante del tiempo, así que es muy importante que el código |
244 instante del tiempo, asà que es muy importante que el código |
245 sea bueno y les permita modificarlo facilmente. El resultado |
245 sea bueno y les permita modificarlo facilmente. El resultado |
246 final será un mejor software al que los programadores |
246 final será un mejor software al que los programadores |
247 querrán extender. |
247 querrán extender. |
248 </para> |
248 </para> |
249 </sect1> |
249 </sect1> |
250 |
250 |
251 <!-- Coding Style --> |
251 <!-- Coding Style --> |
252 |
252 |
253 <sect1 id="code-style"> |
253 <sect1 id="code-style"> |
254 <title>Estilo de programación</title> |
254 <title>Estilo de programación</title> |
255 |
255 |
256 <para> |
256 <para> |
257 ‘El estilo de programación’ se refiere a la forma en |
257 ‘El estilo de programación’ se refiere a la forma en |
258 que se da formato al código fuente. Para C, esto involucra |
258 que se da formato al código fuente. Para C, esto involucra |
259 la forma en que se ubican las llaves, se indenta el código y |
259 la forma en que se ubican las llaves, se indenta el código y |
260 se utilizan los paréntesis. GNOME tiene una mezcla de estilos |
260 se utilizan los paréntesis. GNOME tiene una mezcla de estilos |
261 de programación y no se obliga el uso de ninguno de ellos. Lo más |
261 de programación y no se obliga el uso de ninguno de ellos. Lo más |
262 importante es que el código sea consistente dentro de un programa |
262 importante es que el código sea consistente dentro de un programa |
263 o una biblioteca — el código con un formato desordenado |
263 o una biblioteca — el código con un formato desordenado |
264 no es aceptable debido a que es difícil de leer. |
264 no es aceptable debido a que es difÃcil de leer. |
265 </para> |
265 </para> |
266 |
266 |
267 <para> |
267 <para> |
268 Cuando escribas un nuevo programa o biblioteca, sigue un |
268 Cuando escribas un nuevo programa o biblioteca, sigue un |
269 estilo consistente de ubicación de llaves y de indentación. |
269 estilo consistente de ubicación de llaves y de indentación. |
270 Si no tienes ninguna preferencia personal de estilo, |
270 Si no tienes ninguna preferencia personal de estilo, |
271 recomendamos el estilo de programación del núcleo de Linux o |
271 recomendamos el estilo de programación del núcleo de Linux o |
272 el estilo de programación de GNU. |
272 el estilo de programación de GNU. |
273 </para> |
273 </para> |
274 |
274 |
275 <para> |
275 <para> |
276 Lee el nodo de info <filename>(Standards)Writing C</filename> |
276 Lee el nodo de info <filename>(Standards)Writing C</filename> |
277 en la documentación de GNU. Luego, obtén el código fuente |
277 en la documentación de GNU. Luego, obtén el código fuente |
278 de Linux y lee el archivo |
278 de Linux y lee el archivo |
279 <filename>linux/Documentation/CodingStyle</filename>, e |
279 <filename>linux/Documentation/CodingStyle</filename>, e |
280 ignora los chistes de Linus. Estos dos documentos te darán |
280 ignora los chistes de Linus. Estos dos documentos te darán |
281 una buena idea de nuestras recomendaciones para el código de |
281 una buena idea de nuestras recomendaciones para el código de |
282 GNOME. |
282 GNOME. |
283 </para> |
283 </para> |
284 |
284 |
285 <!-- Indentation Style --> |
285 <!-- Indentation Style --> |
286 |
286 |
287 <sect2 id="indent"> |
287 <sect2 id="indent"> |
288 <title>Estilo de indentación</title> |
288 <title>Estilo de indentación</title> |
289 |
289 |
290 <para> |
290 <para> |
291 Para el código del núcleo de GNOME preferimos el estilo |
291 Para el código del núcleo de GNOME preferimos el estilo |
292 de indentación del núcleo de Linux. Usa tabuladores |
292 de indentación del núcleo de Linux. Usa tabuladores |
293 de 8 espacios para la indentación. |
293 de 8 espacios para la indentación. |
294 </para> |
294 </para> |
295 |
295 |
296 <para> |
296 <para> |
297 Usar tabuladores de 8 espacios para indentación proporciona |
297 Usar tabuladores de 8 espacios para indentación proporciona |
298 un número de beneficios. Permite que el código sea más |
298 un número de beneficios. Permite que el código sea más |
299 fácil de leer, ya que la indentación se marca claramente. |
299 fácil de leer, ya que la indentación se marca claramente. |
300 También ayuda a mantener el código ordenado |
300 También ayuda a mantener el código ordenado |
301 forzando a dividir funciones en trozos más modulares y |
301 forzando a dividir funciones en trozos más modulares y |
302 bien definidos — si la indentación va más allá del |
302 bien definidos — si la indentación va más allá del |
303 margen derecho, significa que la función está mal |
303 margen derecho, significa que la función está mal |
304 diseñada y que debiera dividirse para hacerla más modular |
304 diseñada y que debiera dividirse para hacerla más modular |
305 o bien, repensarla. |
305 o bien, repensarla. |
306 </para> |
306 </para> |
307 |
307 |
308 <para> |
308 <para> |
309 Los tabuladores de 8 espacios para indentación también |
309 Los tabuladores de 8 espacios para indentación también |
310 ayudan al diseño de funciones que encajen bien en la pantalla, |
310 ayudan al diseño de funciones que encajen bien en la pantalla, |
311 lo cual significa que las personas puedan entender el código |
311 lo cual significa que las personas puedan entender el código |
312 sin tener que desplazarse atrás y adelante para entenderlo. |
312 sin tener que desplazarse atrás y adelante para entenderlo. |
313 </para> |
313 </para> |
314 |
314 |
315 <para> |
315 <para> |
316 Si usas &Emacs;, entonces puedes seleccionar el estilo de |
316 Si usas &Emacs;, entonces puedes seleccionar el estilo de |
317 indentación del núcleo de Linux incluyendo en el |
317 indentación del núcleo de Linux incluyendo en el |
318 archivo <filename>.emacs</filename> lo siguiente: |
318 archivo <filename>.emacs</filename> lo siguiente: |
319 |
319 |
320 <programlisting> |
320 <programlisting> |
321 (add-hook 'c-mode-common-hook |
321 (add-hook 'c-mode-common-hook |
322 (lambda () |
322 (lambda () |
323 (c-set-style "k&r") |
323 (c-set-style "k&r") |
324 (setq c-basic-offset 8)))</programlisting> |
324 (setq c-basic-offset 8)))</programlisting> |
325 |
325 |
326 En los nuevos Emacs o con el nuevo cc-mode, puedes ser capaz |
326 En los nuevos Emacs o con el nuevo cc-mode, puedes ser capaz |
327 de hacerlo más simple con: |
327 de hacerlo más simple con: |
328 |
328 |
329 <programlisting> |
329 <programlisting> |
330 (add-hook 'c-mode-common-hook |
330 (add-hook 'c-mode-common-hook |
331 (lambda () |
331 (lambda () |
332 (c-set-style "linux")))</programlisting> |
332 (c-set-style "linux")))</programlisting> |
333 </para> |
333 </para> |
334 |
334 |
335 <para> |
335 <para> |
336 El estilo de indentación de GNU es el predeterminado para |
336 El estilo de indentación de GNU es el predeterminado para |
337 &Emacs;, así que no es necesario agregar nada en el |
337 &Emacs;, asà que no es necesario agregar nada en el |
338 archivo <filename>.emacs</filename> para habilitarlo. |
338 archivo <filename>.emacs</filename> para habilitarlo. |
339 Si deseas seleccionarlo explícitamente, sustituye |
339 Si deseas seleccionarlo explÃcitamente, sustituye |
340 «gnu» por «linux» en el ejemplo anterior. |
340 «gnu» por «linux» en el ejemplo anterior. |
341 </para> |
341 </para> |
342 |
342 |
343 <para> |
343 <para> |
344 Si usas &Vim;, entonces puedes seleccionar el estilo |
344 Si usas &Vim;, entonces puedes seleccionar el estilo |
345 de indentación del núcleo de Linux incluyendo el |
345 de indentación del núcleo de Linux incluyendo el |
346 siguiente fragmento en el archivo |
346 siguiente fragmento en el archivo |
347 <filename>.vimrc</filename>: |
347 <filename>.vimrc</filename>: |
348 |
348 |
349 <programlisting> |
349 <programlisting> |
350 set ts=8 |
350 set ts=8 |
385 |
385 |
386 <sect2 id="naming"> |
386 <sect2 id="naming"> |
387 <title>Convenciones de nombres</title> |
387 <title>Convenciones de nombres</title> |
388 |
388 |
389 <para> |
389 <para> |
390 Es importante seguir una buena convención de nombres para |
390 Es importante seguir una buena convención de nombres para |
391 los símbolos de los programas. Es específicamente |
391 los sÃmbolos de los programas. Es especÃficamente |
392 importante para las bibliotecas, ya que no debería |
392 importante para las bibliotecas, ya que no deberÃa |
393 ensuciarse el espacio de nombres global — es muy |
393 ensuciarse el espacio de nombres global — es muy |
394 molesto cuando una biblioteca tiene símbolos nombrados |
394 molesto cuando una biblioteca tiene sÃmbolos nombrados |
395 desordenadamente que chocan con nombres que pueda |
395 desordenadamente que chocan con nombres que pueda |
396 querer usar en sus programas. |
396 querer usar en sus programas. |
397 </para> |
397 </para> |
398 |
398 |
399 <para> |
399 <para> |
400 Los nombres de las funciones deberían ser de la forma |
400 Los nombres de las funciones deberÃan ser de la forma |
401 <function>modulo_submodulo_operacion</function>, por ejemplo, |
401 <function>modulo_submodulo_operacion</function>, por ejemplo, |
402 <function>gnome_canvas_set_scroll_region</function> o |
402 <function>gnome_canvas_set_scroll_region</function> o |
403 <function>gnome_mime_get_keys</function>. Esta convención |
403 <function>gnome_mime_get_keys</function>. Esta convención |
404 elimina las colisiones de nombres de símbolos entre módulos. |
404 elimina las colisiones de nombres de sÃmbolos entre módulos. |
405 Es muy importante para las bibliotecas. |
405 Es muy importante para las bibliotecas. |
406 </para> |
406 </para> |
407 |
407 |
408 <para> |
408 <para> |
409 Los símbolos deben tener nombres descriptivos. Como Linus |
409 Los sÃmbolos deben tener nombres descriptivos. Como Linus |
410 dice, no use <function>cntusr()</function>, sino que use |
410 dice, no use <function>cntusr()</function>, sino que use |
411 <function>count_active_users()</function>. Esto permite |
411 <function>count_active_users()</function>. Esto permite |
412 que el código sea más fácil de leer y casi se auto |
412 que el código sea más fácil de leer y casi se auto |
413 documenta. |
413 documenta. |
414 </para> |
414 </para> |
415 |
415 |
416 <para> |
416 <para> |
417 Intente usar las mismas convenciones de nombre que tienen |
417 Intente usar las mismas convenciones de nombre que tienen |
418 GTK+ y las bibliotecas de GNOME: |
418 GTK+ y las bibliotecas de GNOME: |
419 |
419 |
420 <itemizedlist> |
420 <itemizedlist> |
421 <listitem> |
421 <listitem> |
422 <para> |
422 <para> |
423 Los nombres de las funciones en minúsculas, con líneas |
423 Los nombres de las funciones en minúsculas, con lÃneas |
424 de subrayado para separar palabras, tal como: |
424 de subrayado para separar palabras, tal como: |
425 <function>gnome_canvas_set_scroll_region()</function>, |
425 <function>gnome_canvas_set_scroll_region()</function>, |
426 <function>gnome_mime_get_keys()</function>. |
426 <function>gnome_mime_get_keys()</function>. |
427 </para> |
427 </para> |
428 </listitem> |
428 </listitem> |
429 |
429 |
430 <listitem> |
430 <listitem> |
431 <para> |
431 <para> |
432 Las macros y las enumeraciones en mayúsculas, con líneas |
432 Las macros y las enumeraciones en mayúsculas, con lÃneas |
433 de subrayado para separar palabras, tal como: |
433 de subrayado para separar palabras, tal como: |
434 <symbol>GNOMEUIINFO_SUBTREE()</symbol> para una macro y |
434 <symbol>GNOMEUIINFO_SUBTREE()</symbol> para una macro y |
435 <symbol>GNOME_INTERACT_NONE</symbol> para un valor |
435 <symbol>GNOME_INTERACT_NONE</symbol> para un valor |
436 enumerado. |
436 enumerado. |
437 </para> |
437 </para> |
438 </listitem> |
438 </listitem> |
439 |
439 |
440 <listitem> |
440 <listitem> |
441 <para> |
441 <para> |
442 Los nombres de tipos y estructuras usan una mezcla de |
442 Los nombres de tipos y estructuras usan una mezcla de |
443 mayúsculas y minúsculas, tal como: |
443 mayúsculas y minúsculas, tal como: |
444 <symbol>GnomeCanvasItem</symbol>, |
444 <symbol>GnomeCanvasItem</symbol>, |
445 <symbol>GnomeIconList</symbol>. |
445 <symbol>GnomeIconList</symbol>. |
446 </para> |
446 </para> |
447 </listitem> |
447 </listitem> |
448 </itemizedlist> |
448 </itemizedlist> |
449 |
449 |
450 Al utilizar líneas de subrayado para separar palabras el |
450 Al utilizar lÃneas de subrayado para separar palabras el |
451 código estará menos apretado y facilita la edición, ya |
451 código estará menos apretado y facilita la edición, ya |
452 que puede usar las secuencias de teclas que permiten |
452 que puede usar las secuencias de teclas que permiten |
453 navegar entre palabras más rápidamente en cualquier editor. |
453 navegar entre palabras más rápidamente en cualquier editor. |
454 </para> |
454 </para> |
455 |
455 |
456 <para> |
456 <para> |
457 Si estás escribiendo una biblioteca, entonces puedes necesitar |
457 Si estás escribiendo una biblioteca, entonces puedes necesitar |
458 exportar símbolos que serán usados sólo dentro de la |
458 exportar sÃmbolos que serán usados sólo dentro de la |
459 biblioteca. Por ejemplo, dos de los archivos objeto que |
459 biblioteca. Por ejemplo, dos de los archivos objeto que |
460 componen la biblioteca <filename>libfoo.so</filename> pueden |
460 componen la biblioteca <filename>libfoo.so</filename> pueden |
461 requerir acceder a símbolos ubicados en el otro archivo, |
461 requerir acceder a sÃmbolos ubicados en el otro archivo, |
462 pero se tiene la intención que éstos símbolos no sean |
462 pero se tiene la intención que éstos sÃmbolos no sean |
463 utilizados desde los programas de usuario. En este caso, |
463 utilizados desde los programas de usuario. En este caso, |
464 coloca una línea de subrayado antes del nombre de la |
464 coloca una lÃnea de subrayado antes del nombre de la |
465 función y haz que la primera palabra siga la convención |
465 función y haz que la primera palabra siga la convención |
466 estándar módulo/submódulo. Por ejemplo, podrías tener |
466 estándar módulo/submódulo. Por ejemplo, podrÃas tener |
467 una función llamada |
467 una función llamada |
468 <function>_foo_internal_frobnicate()</function>. |
468 <function>_foo_internal_frobnicate()</function>. |
469 </para> |
469 </para> |
470 |
470 |
471 <!-- Consistency in Naming --> |
471 <!-- Consistency in Naming --> |
472 |
472 |
473 <sect3 id="consist"> |
473 <sect3 id="consist"> |
474 <title>Consistencia entre nombres</title> |
474 <title>Consistencia entre nombres</title> |
475 |
475 |
476 <para> |
476 <para> |
477 Es importante que las variables se nombren de manera |
477 Es importante que las variables se nombren de manera |
478 consistente. Por ejemplo, un módulo que manipula una |
478 consistente. Por ejemplo, un módulo que manipula una |
479 lista puedes elegir nombrar las variables que mantienen |
479 lista puedes elegir nombrar las variables que mantienen |
480 un puntero a la lista como «<symbol>l</symbol>», |
480 un puntero a la lista como «<symbol>l</symbol>», |
481 por elegancia y simplicidad. Sin embargo, es importante que |
481 por elegancia y simplicidad. Sin embargo, es importante que |
482 un módulo que manipula widgets y tamaños no use variables |
482 un módulo que manipula widgets y tamaños no use variables |
483 llamadas «<symbol>w</symbol>» tanto para |
483 llamadas «<symbol>w</symbol>» tanto para |
484 widgets y anchos («width») (como en valores de ancho/alto); |
484 widgets y anchos («width») (como en valores de ancho/alto); |
485 esto podría hacer que el código sea inconsistente |
485 esto podrÃa hacer que el código sea inconsistente |
486 y difícil de leer. |
486 y difÃcil de leer. |
487 </para> |
487 </para> |
488 |
488 |
489 <para> |
489 <para> |
490 Por supuesto, nombre muy cortos y elegantes solamente deberían |
490 Por supuesto, nombre muy cortos y elegantes solamente deberÃan |
491 ser usados para variables locales de funciones. |
491 ser usados para variables locales de funciones. |
492 Nunca llame una variable global «<symbol>x</symbol>»; use |
492 Nunca llame una variable global «<symbol>x</symbol>»; use |
493 un nombre más largo que indique lo que significa. |
493 un nombre más largo que indique lo que significa. |
494 </para> |
494 </para> |
495 </sect3> |
495 </sect3> |
496 </sect2> |
496 </sect2> |
497 |
497 |
498 <!-- Cleanliness --> |
498 <!-- Cleanliness --> |
499 |
499 |
500 <sect2 id="clean"> |
500 <sect2 id="clean"> |
501 <title>Limpieza</title> |
501 <title>Limpieza</title> |
502 |
502 |
503 <para> |
503 <para> |
504 El código de GNOME debe ser tan limpio como sea posible. |
504 El código de GNOME debe ser tan limpio como sea posible. |
505 Esto implica usar un estilo de indentación consistente |
505 Esto implica usar un estilo de indentación consistente |
506 y una buena convención para nombrar símbolos, como se |
506 y una buena convención para nombrar sÃmbolos, como se |
507 ha indicado anteriormente. Esto también implica lo |
507 ha indicado anteriormente. Esto también implica lo |
508 siguiente. |
508 siguiente. |
509 </para> |
509 </para> |
510 |
510 |
511 <para> |
511 <para> |
512 Aprender el uso correcto de la palabra reservada |
512 Aprender el uso correcto de la palabra reservada |
513 <symbol>static</symbol>. |
513 <symbol>static</symbol>. |
514 <emphasis>No</emphasis> declarar todos los símbolos como |
514 <emphasis>No</emphasis> declarar todos los sÃmbolos como |
515 globales. Esto tiene la ventaja de poder usar nombres |
515 globales. Esto tiene la ventaja de poder usar nombres |
516 más cortos dentro de las funciones en un sólo archivo |
516 más cortos dentro de las funciones en un sólo archivo |
517 fuente, ya que no son globalmente visibles y por |
517 fuente, ya que no son globalmente visibles y por |
518 consiguiente no necesitas emplear el prefijo |
518 consiguiente no necesitas emplear el prefijo |
519 módulo/submódulo. |
519 módulo/submódulo. |
520 </para> |
520 </para> |
521 |
521 |
522 <para> |
522 <para> |
523 Aprender el uso correcto de la palabra reservada |
523 Aprender el uso correcto de la palabra reservada |
524 <symbol>const</symbol>. Úsala consistentemente, |
524 <symbol>const</symbol>. Úsala consistentemente, |
525 así permitirás al compilador que atrape muchos |
525 asà permitirás al compilador que atrape muchos |
526 errores estúpidos. |
526 errores estúpidos. |
527 </para> |
527 </para> |
528 |
528 |
529 <para> |
529 <para> |
530 Si tienes una función que retorna un puntero a |
530 Si tienes una función que retorna un puntero a |
531 un dato interno que se supone que el usuario |
531 un dato interno que se supone que el usuario |
532 no debe liberar, deberías usar el modificador |
532 no debe liberar, deberÃas usar el modificador |
533 <symbol>const</symbol>. Este avisará al usuario si intenta |
533 <symbol>const</symbol>. Este avisará al usuario si intenta |
534 hacer alguna operación incorrecta, por ejemplo: |
534 hacer alguna operación incorrecta, por ejemplo: |
535 |
535 |
536 <programlisting> |
536 <programlisting> |
537 const char *gnome_mime_get_info (const char *info);</programlisting> |
537 const char *gnome_mime_get_info (const char *info);</programlisting> |
538 |
538 |
539 El compilador avisará si el usuario intenta liberar |
539 El compilador avisará si el usuario intenta liberar |
540 la cadena retornada. Esto puede atrapar muchos |
540 la cadena retornada. Esto puede atrapar muchos |
541 errores. |
541 errores. |
542 </para> |
542 </para> |
543 |
543 |
544 <para> |
544 <para> |
545 Si tienes «valores mágicos» en el programa o |
545 Si tienes «valores mágicos» en el programa o |
546 biblioteca, usa macros que los definan en vez de usarlos |
546 biblioteca, usa macros que los definan en vez de usarlos |
547 directamente en el código: |
547 directamente en el código: |
548 |
548 |
549 <programlisting> |
549 <programlisting> |
550 /* Amount of padding for GUI elements */ |
550 /* Amount of padding for GUI elements */ |
551 #define GNOME_PAD 8 |
551 #define GNOME_PAD 8 |
552 #define GNOME_PAD_SMALL 4 |
552 #define GNOME_PAD_SMALL 4 |
590 GNOME_CANVAS_UPDATE_CLIP = 1 << 2, |
590 GNOME_CANVAS_UPDATE_CLIP = 1 << 2, |
591 GNOME_CANVAS_UPDATE_VISIBILITY = 1 << 3, |
591 GNOME_CANVAS_UPDATE_VISIBILITY = 1 << 3, |
592 GNOME_CANVAS_UPDATE_IS_VISIBLE = 1 << 4 |
592 GNOME_CANVAS_UPDATE_IS_VISIBLE = 1 << 4 |
593 };]]></programlisting> |
593 };]]></programlisting> |
594 |
594 |
595 Esto hace más fácil modificar la lista de valores y menos |
595 Esto hace más fácil modificar la lista de valores y menos |
596 propenso a error que especificando los valores a mano. También |
596 propenso a error que especificando los valores a mano. También |
597 permite usar estos valores como símbolos en un depurador. |
597 permite usar estos valores como sÃmbolos en un depurador. |
598 </para> |
598 </para> |
599 |
599 |
600 <para> |
600 <para> |
601 No escribas código ofuscado, intenta que sea espartano. |
601 No escribas código ofuscado, intenta que sea espartano. |
602 Para clarificar una expresión, no uses más paréntesis que |
602 Para clarificar una expresión, no uses más paréntesis que |
603 los necesarios. Usa espacios antes de los paréntesis y |
603 los necesarios. Usa espacios antes de los paréntesis y |
604 después de las comas y también alrededor de los operadores |
604 después de las comas y también alrededor de los operadores |
605 binarios. |
605 binarios. |
606 </para> |
606 </para> |
607 |
607 |
608 <para> |
608 <para> |
609 No escribas hacks en el código. En vez de escribir un |
609 No escribas hacks en el código. En vez de escribir un |
610 hack feo, reescribe el código para que quede limpio, |
610 hack feo, reescribe el código para que quede limpio, |
611 extensible y mantenible. |
611 extensible y mantenible. |
612 </para> |
612 </para> |
613 |
613 |
614 <para> |
614 <para> |
615 Asegúrate de que el código compila absolutamente sin ningún |
615 Asegúrate de que el código compila absolutamente sin ningún |
616 aviso del compilador. Esto te ayudará a atrapar errores |
616 aviso del compilador. Esto te ayudará a atrapar errores |
617 estúpidos. Usa los prototipos de las funciones en los |
617 estúpidos. Usa los prototipos de las funciones en los |
618 archivos de encabezados de forma consistente. |
618 archivos de encabezados de forma consistente. |
619 </para> |
619 </para> |
620 |
620 |
621 <para> |
621 <para> |
622 Dentro de GNOME puedes usar la macro de Autoconf |
622 Dentro de GNOME puedes usar la macro de Autoconf |
623 <symbol>GNOME_COMPILE_WARNINGS</symbol> en el archivo |
623 <symbol>GNOME_COMPILE_WARNINGS</symbol> en el archivo |
624 <filename>configure.in</filename>. Esto permitirá contar |
624 <filename>configure.in</filename>. Esto permitirá contar |
625 con un buen conjunto de avisos del compilador de una manera |
625 con un buen conjunto de avisos del compilador de una manera |
626 portable. |
626 portable. |
627 </para> |
627 </para> |
628 |
628 |
629 <para> |
629 <para> |
630 Comenta el código. Coloca comentarios antes de |
630 Comenta el código. Coloca comentarios antes de |
631 cada función para decir que hace. No digas cómo lo hace |
631 cada función para decir que hace. No digas cómo lo hace |
632 a menos que sea absolutamente necesario; debería ser |
632 a menos que sea absolutamente necesario; deberÃa ser |
633 obvio al leer el código. Si no lo fuera, entonces |
633 obvio al leer el código. Si no lo fuera, entonces |
634 puedes desear reescribirla hasta que sea fácil de |
634 puedes desear reescribirla hasta que sea fácil de |
635 entender. |
635 entender. |
636 </para> |
636 </para> |
637 |
637 |
638 <para> |
638 <para> |
639 Cuando documentes las funciones de la API de una biblioteca, |
639 Cuando documentes las funciones de la API de una biblioteca, |
640 sigue las directrices indicadas en el archivo |
640 sigue las directrices indicadas en el archivo |
641 <filename>gnome-libs/devel-docs/api-comment-style.txt</filename>. |
641 <filename>gnome-libs/devel-docs/api-comment-style.txt</filename>. |
642 Esto permite que el código fuente pueda proporcionar documentación |
642 Esto permite que el código fuente pueda proporcionar documentación |
643 en línea, que posteriormente se extrae mediante el sistema |
643 en lÃnea, que posteriormente se extrae mediante el sistema |
644 <application>gtk-doc</application> para crear un manual DocBook |
644 <application>gtk-doc</application> para crear un manual DocBook |
645 de forma automática. |
645 de forma automática. |
646 </para> |
646 </para> |
647 |
647 |
648 <!-- Portability considerations --> |
648 <!-- Portability considerations --> |
649 |
649 |
650 <sect3 id="portability"> |
650 <sect3 id="portability"> |
651 <title>Consideraciones de portabilidad</title> |
651 <title>Consideraciones de portabilidad</title> |
652 |
652 |
653 <para> |
653 <para> |
654 Se construye GNOME en muchas plataformas diferentes. |
654 Se construye GNOME en muchas plataformas diferentes. |
655 Se puede asumir que serán plataformas más o menos tipo Unix; |
655 Se puede asumir que serán plataformas más o menos tipo Unix; |
656 hasta el momento GNOME no ha sido portado a sistema no-Unix, |
656 hasta el momento GNOME no ha sido portado a sistema no-Unix, |
657 así que se puede asumir que los servicios estándares de |
657 asà que se puede asumir que los servicios estándares de |
658 Unix estarán disponibles.<footnote> |
658 Unix estarán disponibles.<footnote> |
659 <para> |
659 <para> |
660 ¿Servicios estándar de Unix? Por supuesto que estamos |
660 ¿Servicios estándar de Unix? Por supuesto que estamos |
661 bromeando. |
661 bromeando. |
662 </para> |
662 </para> |
663 </footnote> |
663 </footnote> |
664 </para> |
664 </para> |
665 |
665 |
666 <para> |
666 <para> |
667 Recuerda que el mundo no es tu propio equipo con GNU/Linux; |
667 Recuerda que el mundo no es tu propio equipo con GNU/Linux; |
668 las gente realmente usa otros tipos de máquinas. |
668 las gente realmente usa otros tipos de máquinas. |
669 </para> |
669 </para> |
670 |
670 |
671 <para> |
671 <para> |
672 Intenta no usar extensiones específicas de |
672 Intenta no usar extensiones especÃficas de |
673 <application>GCC</application> debido a que éstas no |
673 <application>GCC</application> debido a que éstas no |
674 funcionarán con otros compiladores. Si realmente debes |
674 funcionarán con otros compiladores. Si realmente debes |
675 hacer uso de tal cosa, ve la forma en que se hace |
675 hacer uso de tal cosa, ve la forma en que se hace |
676 en <application>Glib</application> con el conjunto de |
676 en <application>Glib</application> con el conjunto de |
677 macros G_GNUC; asegúrate también de incluir código |
677 macros G_GNUC; asegúrate también de incluir código |
678 que funcione con compiladores ISO C. Si sólo tienes |
678 que funcione con compiladores ISO C. Si sólo tienes |
679 disponible <application>GCC</application>, aprende a usar |
679 disponible <application>GCC</application>, aprende a usar |
680 las opciones <option>-ansi -pedantic</option> que |
680 las opciones <option>-ansi -pedantic</option> que |
681 permiten probar código sospechoso. |
681 permiten probar código sospechoso. |
682 </para> |
682 </para> |
683 |
683 |
684 <para> |
684 <para> |
685 Recuerda que algunas plataformas no disponen de |
685 Recuerda que algunas plataformas no disponen de |
686 <application>GCC</application> o que |
686 <application>GCC</application> o que |
687 <application>GDB</application> puede ser inusable en ellos, |
687 <application>GDB</application> puede ser inusable en ellos, |
688 y se querrán usar otros compiladores y depuradores. |
688 y se querrán usar otros compiladores y depuradores. |
689 </para> |
689 </para> |
690 </sect3> |
690 </sect3> |
691 |
691 |
692 <!-- GTK+-related Issues --> |
692 <!-- GTK+-related Issues --> |
693 |
693 |
694 <sect3 id="gtk"> |
694 <sect3 id="gtk"> |
695 <title>Tópicos relacionados con GTK+</title> |
695 <title>Tópicos relacionados con GTK+</title> |
696 |
696 |
697 <para> |
697 <para> |
698 GTK+ permite hacer mucha magia y ofuscación con manejadores |
698 GTK+ permite hacer mucha magia y ofuscación con manejadores |
699 de señal, pasar cerraduras y conjuntos de datos. Si te |
699 de señal, pasar cerraduras y conjuntos de datos. Si te |
700 encuentras utilizando muchos |
700 encuentras utilizando muchos |
701 <function>gtk_object_set_data()</function> en un mismo lugar, |
701 <function>gtk_object_set_data()</function> en un mismo lugar, |
702 o estas pasando estados de forma extraña a través de manejadores |
702 o estas pasando estados de forma extraña a través de manejadores |
703 de señales, reescribe el código. Si necesitas adjuntar muchos |
703 de señales, reescribe el código. Si necesitas adjuntar muchos |
704 datos a un objeto en particular, entonces es un buen candidato |
704 datos a un objeto en particular, entonces es un buen candidato |
705 para una nueva clase derivada, que no sólo hará al código |
705 para una nueva clase derivada, que no sólo hará al código |
706 más limpio, sino que también lo hará más extensible. |
706 más limpio, sino que también lo hará más extensible. |
707 </para> |
707 </para> |
708 |
708 |
709 <para> |
709 <para> |
710 Mucha de la heurística en manejadores de eventos complicadas |
710 Mucha de la heurÃstica en manejadores de eventos complicadas |
711 a menudo se pueden reemplazar limpiando el código a través |
711 a menudo se pueden reemplazar limpiando el código a través |
712 de una máquina de estados. Esto es útil cuando se quieren |
712 de una máquina de estados. Esto es útil cuando se quieren |
713 implementar cosas truculentas como selección y comportamientos |
713 implementar cosas truculentas como selección y comportamientos |
714 de arrastrado, y hará al código más fácil de depurar y extender. |
714 de arrastrado, y hará al código más fácil de depurar y extender. |
715 </para> |
715 </para> |
716 </sect3> |
716 </sect3> |
717 </sect2> |
717 </sect2> |
718 </sect1> |
718 </sect1> |
719 |
719 |
720 <!-- Correctness and Robustness --> |
720 <!-- Correctness and Robustness --> |
721 |
721 |
722 <sect1 id="robust"> |
722 <sect1 id="robust"> |
723 <title>Corrección y robustez</title> |
723 <title>Corrección y robustez</title> |
724 |
724 |
725 <para> |
725 <para> |
726 Es extremadamente importante que el código de GNOME sea |
726 Es extremadamente importante que el código de GNOME sea |
727 correcto y robusto. Esto significa que el código debería hacer |
727 correcto y robusto. Esto significa que el código deberÃa hacer |
728 lo que se espera que haga y debería manejar bien las condiciones |
728 lo que se espera que haga y deberÃa manejar bien las condiciones |
729 de excepción. Aunque esto pueda parecer obvio, esta sección |
729 de excepción. Aunque esto pueda parecer obvio, esta sección |
730 dará algunas ideas para asegurar la corrección de tu código |
730 dará algunas ideas para asegurar la corrección de tu código |
731 de GNOME. Esto es muy importante, ya que los usuarios esperan |
731 de GNOME. Esto es muy importante, ya que los usuarios esperan |
732 y merecen un software confiable que se ejecute correctamente |
732 y merecen un software confiable que se ejecute correctamente |
733 y que no se caiga. |
733 y que no se caiga. |
734 </para> |
734 </para> |
735 |
735 |
736 <!-- Ensuring Consistency --> |
736 <!-- Ensuring Consistency --> |
737 |
737 |
738 <sect2 id="ensure"> |
738 <sect2 id="ensure"> |
739 <title>Cómo asegurar la consistencia</title> |
739 <title>Cómo asegurar la consistencia</title> |
740 |
740 |
741 <para> |
741 <para> |
742 <!-- FIXME: Buscar un mejor termino para "assertion" --> |
742 <!-- FIXME: Buscar un mejor termino para "assertion" --> |
743 Utiliza las macros de aserción de Glib para asegurarte |
743 Utiliza las macros de aserción de Glib para asegurarte |
744 que el estado de un programa es consistente. Estas macros |
744 que el estado de un programa es consistente. Estas macros |
745 ayudan a localizar errores muy rápidamente y se gastará |
745 ayudan a localizar errores muy rápidamente y se gastará |
746 mucho menos tiempo en el depurado si se emplean de forma |
746 mucho menos tiempo en el depurado si se emplean de forma |
747 generosa y consistente. |
747 generosa y consistente. |
748 </para> |
748 </para> |
749 |
749 |
750 <para> |
750 <para> |
751 Inserta verificaciones de sanidad en el código en puntos |
751 Inserta verificaciones de sanidad en el código en puntos |
752 importantes como es el inicio de funciones públicas, al |
752 importantes como es el inicio de funciones públicas, al |
753 final de código que realiza una búsqueda que siempre |
753 final de código que realiza una búsqueda que siempre |
754 debe ser exitosa y en cualquier lugar donde |
754 debe ser exitosa y en cualquier lugar donde |
755 el rango de valores calculados es importante. |
755 el rango de valores calculados es importante. |
756 </para> |
756 </para> |
757 </sect2> |
757 </sect2> |
758 |
758 |
831 </variablelist> |
831 </variablelist> |
832 </para> |
832 </para> |
833 |
833 |
834 <para> |
834 <para> |
835 Estas funciones debieran emplearse para imponer |
835 Estas funciones debieran emplearse para imponer |
836 precondiciones en el código y verificar su corrección |
836 precondiciones en el código y verificar su corrección |
837 — piensa en ellas como verificaciones de sanidad |
837 — piensa en ellas como verificaciones de sanidad |
838 en los programas. Debieras usarlas libremente como |
838 en los programas. Debieras usarlas libremente como |
839 asistencia para atrapar los errores rápidamente; una |
839 asistencia para atrapar los errores rápidamente; una |
840 vez que el programa se encuentre completamente depurado, |
840 vez que el programa se encuentre completamente depurado, |
841 puedes compilarlo con estas macros deshabilitadas y así |
841 puedes compilarlo con estas macros deshabilitadas y asà |
842 evitar añadirle sobrecarga al momento de ejecutarlos. |
842 evitar añadirle sobrecarga al momento de ejecutarlos. |
843 </para> |
843 </para> |
844 |
844 |
845 <para> |
845 <para> |
846 Las macros <function>g_return_*()</function> debieran |
846 Las macros <function>g_return_*()</function> debieran |
847 emplearse al inicio de las funciones públicas de las |
847 emplearse al inicio de las funciones públicas de las |
848 bibliotecas, para asegurarse de que los argumentos que se pasan |
848 bibliotecas, para asegurarse de que los argumentos que se pasan |
849 a ellas sean correctos y tengan un rango válido. Si |
849 a ellas sean correctos y tengan un rango válido. Si |
850 una función no retorna valor (por ejemplo, retorna |
850 una función no retorna valor (por ejemplo, retorna |
851 <symbol>void</symbol>), debieras usar |
851 <symbol>void</symbol>), debieras usar |
852 <function>g_return_if_fail()</function>. En caso contrario, |
852 <function>g_return_if_fail()</function>. En caso contrario, |
853 debiera usar <function>g_return_val_if_fail()</function> |
853 debiera usar <function>g_return_val_if_fail()</function> |
854 para retornar un valor ‘seguro’. Cuando |
854 para retornar un valor ‘seguro’. Cuando |
855 se invoca una función de biblioteca que usa estas macros |
855 se invoca una función de biblioteca que usa estas macros |
856 con un argumento incorrecto , se producirá un |
856 con un argumento incorrecto , se producirá un |
857 mensaje de error y continuará la ejecución. El |
857 mensaje de error y continuará la ejecución. El |
858 programa cliente podrá tener algún sobresalto, hacer |
858 programa cliente podrá tener algún sobresalto, hacer |
859 nada o caerse, pero al menos sabrá |
859 nada o caerse, pero al menos sabrá |
860 <emphasis>dónde</emphasis> se le ha pasado un valor |
860 <emphasis>dónde</emphasis> se le ha pasado un valor |
861 incorrecto a la función. |
861 incorrecto a la función. |
862 </para> |
862 </para> |
863 |
863 |
864 <para> |
864 <para> |
865 La macro <function>g_assert()</function> debiera usarse para |
865 La macro <function>g_assert()</function> debiera usarse para |
866 asegurar la consistencia interna de una biblioteca o |
866 asegurar la consistencia interna de una biblioteca o |
867 programa. En vez de retornar de la función y continuar |
867 programa. En vez de retornar de la función y continuar |
868 la ejecución si la condición falla, |
868 la ejecución si la condición falla, |
869 <function>g_assert()</function> producirá en mensaje de error |
869 <function>g_assert()</function> producirá en mensaje de error |
870 e inmediatamente abortará el programa. Esto es para |
870 e inmediatamente abortará el programa. Esto es para |
871 evitar que el programa continúe ejecutándose en un |
871 evitar que el programa continúe ejecutándose en un |
872 estado inconsistente. Debieras usar esta macro para |
872 estado inconsistente. Debieras usar esta macro para |
873 asegurarte de que el programa o biblioteca está usando |
873 asegurarte de que el programa o biblioteca está usando |
874 valores internos sanos. |
874 valores internos sanos. |
875 </para> |
875 </para> |
876 |
876 |
877 <para> |
877 <para> |
878 La macro <function>g_assert_not_reached()</function> se |
878 La macro <function>g_assert_not_reached()</function> se |
879 usa para marcar el lugar en el código que nunca |
879 usa para marcar el lugar en el código que nunca |
880 debiera producirse. Por ejemplo, si tienes una |
880 debiera producirse. Por ejemplo, si tienes una |
881 cláusula <symbol>switch</symbol> y piensas que manejas |
881 cláusula <symbol>switch</symbol> y piensas que manejas |
882 todos los valores posibles en las etiquetas |
882 todos los valores posibles en las etiquetas |
883 <symbol>case</symbol>, entonces debieras colocar |
883 <symbol>case</symbol>, entonces debieras colocar |
884 <function>g_assert_not_reached()</function> en la |
884 <function>g_assert_not_reached()</function> en la |
885 etiqueta <symbol>default</symbol> para asegurarte de que |
885 etiqueta <symbol>default</symbol> para asegurarte de que |
886 el código nunca llegue allá (podría significar que |
886 el código nunca llegue allá (podrÃa significar que |
887 ha perdido algún valor o que el programa se encuentra |
887 ha perdido algún valor o que el programa se encuentra |
888 incorrecto). |
888 incorrecto). |
889 </para> |
889 </para> |
890 |
890 |
891 <para> |
891 <para> |
892 Estas macros ayudan a encontrar errores más rápido |
892 Estas macros ayudan a encontrar errores más rápido |
893 a través de avisos que se producen tan pronto como |
893 a través de avisos que se producen tan pronto como |
894 el programa alcanza un estado incosistente. Úsalos |
894 el programa alcanza un estado incosistente. Úsalos |
895 frecuentemente y encontrarás muchos errores más |
895 frecuentemente y encontrarás muchos errores más |
896 fácilmente. |
896 fácilmente. |
897 </para> |
897 </para> |
898 </sect2> |
898 </sect2> |
899 |
899 |
900 <!-- GTK+-related Issues --> |
900 <!-- GTK+-related Issues --> |
901 |
901 |
902 <sect2 id="assert-gtk"> |
902 <sect2 id="assert-gtk"> |
903 <title>Tópicos relacionados con GTK+</title> |
903 <title>Tópicos relacionados con GTK+</title> |
904 |
904 |
905 <para> |
905 <para> |
906 Debe ser cuidadoso cuando escribas manejadores de eventos |
906 Debe ser cuidadoso cuando escribas manejadores de eventos |
907 — asegurate de que los eventos son manipulados en |
907 — asegurate de que los eventos son manipulados en |
908 las situaciones apropiadas. Es necesario asegurarse de |
908 las situaciones apropiadas. Es necesario asegurarse de |
909 que los manejadores de señales tengan los prototipos |
909 que los manejadores de señales tengan los prototipos |
910 correctos. Esto es muy importante. Recuerda que no |
910 correctos. Esto es muy importante. Recuerda que no |
911 todos los prototipos de manejadores de señal se parecen |
911 todos los prototipos de manejadores de señal se parecen |
912 a lo siguiente: |
912 a lo siguiente: |
913 |
913 |
914 <programlisting> |
914 <programlisting> |
915 static void my_handler (GtkWidget *widget, gpointer data);</programlisting> |
915 static void my_handler (GtkWidget *widget, gpointer data);</programlisting> |
916 |
916 |
917 Por ejemplo, los manejadores de eventos tienen un parámetro |
917 Por ejemplo, los manejadores de eventos tienen un parámetro |
918 extra de evento y retornan <symbol>gint</symbol>. Revisa los |
918 extra de evento y retornan <symbol>gint</symbol>. Revisa los |
919 archivos de encabezado de GTK+ cuando necesites verificarlo. |
919 archivos de encabezado de GTK+ cuando necesites verificarlo. |
920 </para> |
920 </para> |
921 |
921 |
922 <para> |
922 <para> |
923 Asegúrate que el programa trata de una forma apropiada |
923 Asegúrate que el programa trata de una forma apropiada |
924 todas las acciones generadas por el usuario. Recuerda |
924 todas las acciones generadas por el usuario. Recuerda |
925 que el usuario puede cerrar una ventana en cualquier |
925 que el usuario puede cerrar una ventana en cualquier |
926 momento a través del administrador de ventanas; tenlo |
926 momento a través del administrador de ventanas; tenlo |
927 presente y escribe el código necesario para manejar esta |
927 presente y escribe el código necesario para manejar esta |
928 situación. |
928 situación. |
929 </para> |
929 </para> |
930 |
930 |
931 <para> |
931 <para> |
932 Si verificas los modificadores de teclas con una máscara |
932 Si verificas los modificadores de teclas con una máscara |
933 de estado de eventos, por ejemplo, |
933 de estado de eventos, por ejemplo, |
934 <keycombo><keycap>Control</keycap><keycap>F10</keycap></keycombo> |
934 <keycombo><keycap>Control</keycap><keycap>F10</keycap></keycombo> |
935 escribe lo siguiente: |
935 escribe lo siguiente: |
936 |
936 |
937 <programlisting> |
937 <programlisting> |
947 Esto es necesario; si en vez de lo anterior escribes: |
947 Esto es necesario; si en vez de lo anterior escribes: |
948 |
948 |
949 <programlisting> |
949 <programlisting> |
950 if (event->keysym == GDK_F10 && event->state == GDK_CONTROL_MASK)</programlisting> |
950 if (event->keysym == GDK_F10 && event->state == GDK_CONTROL_MASK)</programlisting> |
951 |
951 |
952 entonces el programa no funcionará correctamente si el |
952 entonces el programa no funcionará correctamente si el |
953 usuario tiene, por ejemplo, activada la tecla |
953 usuario tiene, por ejemplo, activada la tecla |
954 <keycap>NumLock</keycap> — <keycap>NumLock</keycap> |
954 <keycap>NumLock</keycap> — <keycap>NumLock</keycap> |
955 también es un modificador, y si está activado, entonces |
955 también es un modificador, y si está activado, entonces |
956 la máscara de estado del evento no será como se espera |
956 la máscara de estado del evento no será como se espera |
957 en el segundo ejemplo. |
957 en el segundo ejemplo. |
958 </para> |
958 </para> |
959 |
959 |
960 <!-- Visuals and Colormaps --> |
960 <!-- Visuals and Colormaps --> |
961 |
961 |
962 <sect3 id="visuals"> |
962 <sect3 id="visuals"> |
963 <title>Vistas y mapas de color</title> |
963 <title>Vistas y mapas de color</title> |
964 |
964 |
965 <para> |
965 <para> |
966 <!-- FIXME: Buscar un término adecuado para "Visual" en |
966 <!-- FIXME: Buscar un término adecuado para "Visual" en |
967 vez de "vista" --> |
967 vez de "vista" --> |
968 Algunos usuarios utilizan tarjetas de vídeo avanzadas |
968 Algunos usuarios utilizan tarjetas de vÃdeo avanzadas |
969 (por ejemplo, SGIs y Suns) que soportan múltiples vistas |
969 (por ejemplo, SGIs y Suns) que soportan múltiples vistas |
970 simúltaneamente. Una vista define la representación en memoria |
970 simúltaneamente. Una vista define la representación en memoria |
971 que usa un dispositivo de hardware para almacenar los |
971 que usa un dispositivo de hardware para almacenar los |
972 contenidos de una imagen. Muchas tarjetas de vídeo de |
972 contenidos de una imagen. Muchas tarjetas de vÃdeo de |
973 PC soportan sólo una vista a la vez, pero el hardware |
973 PC soportan sólo una vista a la vez, pero el hardware |
974 avanzado puede tener diferentes ventanas y pixmaps en |
974 avanzado puede tener diferentes ventanas y pixmaps en |
975 diferentes vistas simultáneamente. |
975 diferentes vistas simultáneamente. |
976 </para> |
976 </para> |
977 |
977 |
978 <para> |
978 <para> |
979 Es importante entender las vistas y mapas de colores si |
979 Es importante entender las vistas y mapas de colores si |
980 vas a escribir código que crea ventanas y pixmaps por tus |
980 vas a escribir código que crea ventanas y pixmaps por tus |
981 propios medios, en vez de utilizar las funciones de alto |
981 propios medios, en vez de utilizar las funciones de alto |
982 nivel como GnomeCanvas y GnomePixmap. Para mayor información, |
982 nivel como GnomeCanvas y GnomePixmap. Para mayor información, |
983 lea el manual de programación de Xlib. |
983 lea el manual de programación de Xlib. |
984 </para> |
984 </para> |
985 |
985 |
986 <para> |
986 <para> |
987 En general, sólo necesitas recordar que la vista y el mapa |
987 En general, sólo necesitas recordar que la vista y el mapa |
988 de colores de un área de dibujo debe coincidir con los de |
988 de colores de un área de dibujo debe coincidir con los de |
989 otra área de dibujo si deseas copiar un trozo desde la |
989 otra área de dibujo si deseas copiar un trozo desde la |
990 primera área de dibujo a la segunda. Si no son las mismas, |
990 primera área de dibujo a la segunda. Si no son las mismas, |
991 podrías obtener el mensaje «BadMatch error» del servidor X y |
991 podrÃas obtener el mensaje «BadMatch error» del servidor X y |
992 tu aplicación muy probablemente abortará su ejecución. |
992 tu aplicación muy probablemente abortará su ejecución. |
993 </para> |
993 </para> |
994 |
994 |
995 <para> |
995 <para> |
996 Si creas un contexto gráfico (GC) y lo compartes para pintar |
996 Si creas un contexto gráfico (GC) y lo compartes para pintar |
997 en varias áreas de dibujo, asegúrate que todas ellas tengan |
997 en varias áreas de dibujo, asegúrate que todas ellas tengan |
998 la misma vista y mapa de colores que fue definido para el |
998 la misma vista y mapa de colores que fue definido para el |
999 GC. Lo mismo se aplica si quieres copiar un área desde un |
999 GC. Lo mismo se aplica si quieres copiar un área desde un |
1000 pixmap a una ventana; ambos deben tener la misma vista y mapa |
1000 pixmap a una ventana; ambos deben tener la misma vista y mapa |
1001 de colores. |
1001 de colores. |
1002 </para> |
1002 </para> |
1003 |
1003 |
1004 <para> |
1004 <para> |
1005 Si no estás seguro de que tu código lo hace correctamente, |
1005 Si no estás seguro de que tu código lo hace correctamente, |
1006 pregunta educadamente, en una de las listas de correo de |
1006 pregunta educadamente, en una de las listas de correo de |
1007 desarrollo de GNOME, si alguien puede realizar una prueba con |
1007 desarrollo de GNOME, si alguien puede realizar una prueba con |
1008 una tarjeta de video que soporta esta característica. Dicha |
1008 una tarjeta de video que soporta esta caracterÃstica. Dicha |
1009 persona sabrá como arreglar el problema y te dirá al respecto. |
1009 persona sabrá como arreglar el problema y te dirá al respecto. |
1010 </para> |
1010 </para> |
1011 </sect3> |
1011 </sect3> |
1012 </sect2> |
1012 </sect2> |
1013 |
1013 |
1014 <!-- Unix-related Issues --> |
1014 <!-- Unix-related Issues --> |
1097 |
1097 |
1098 fd = open (filename, O_CREAT | O_EXCL | O_TRUNC | O_RDWR, 0600); |
1098 fd = open (filename, O_CREAT | O_EXCL | O_TRUNC | O_RDWR, 0600); |
1099 free (filename); |
1099 free (filename); |
1100 } while (fd == -1);</programlisting> |
1100 } while (fd == -1);</programlisting> |
1101 |
1101 |
1102 Recuerde liberar <symbol>filename</symbol> usando la función |
1102 Recuerde liberar <symbol>filename</symbol> usando la función |
1103 <function>free()</function> y llamar a las funciones |
1103 <function>free()</function> y llamar a las funciones |
1104 <function>close()</function> y <function>unlink()</function> |
1104 <function>close()</function> y <function>unlink()</function> |
1105 con el archivo respectivo cuando haya terminado; aquí |
1105 con el archivo respectivo cuando haya terminado; aquà |
1106 liberamos <symbol>filename</symbol> con <function>free()</function> |
1106 liberamos <symbol>filename</symbol> con <function>free()</function> |
1107 inmediatamente y así no causará una pérdida de memoria. |
1107 inmediatamente y asà no causará una pérdida de memoria. |
1108 </para> |
1108 </para> |
1109 |
1109 |
1110 <para> |
1110 <para> |
1111 Si deseas usar la biblioteca estándar de E/S, puede usar la |
1111 Si deseas usar la biblioteca estándar de E/S, puede usar la |
1112 función <function>fdopen()</function> para transformar el |
1112 función <function>fdopen()</function> para transformar el |
1113 descriptor de archivo en <symbol>FILE *</symbol>, o puedes |
1113 descriptor de archivo en <symbol>FILE *</symbol>, o puedes |
1114 usar la función <function>tmpfile()</function> para hacerlo |
1114 usar la función <function>tmpfile()</function> para hacerlo |
1115 en un solo paso. |
1115 en un solo paso. |
1116 </para> |
1116 </para> |
1117 |
1117 |
1118 <para> |
1118 <para> |
1119 Intenta no usar buffers de tamaño fijo. Los buffers de tamaño |
1119 Intenta no usar buffers de tamaño fijo. Los buffers de tamaño |
1120 fijo para cadenas constituyen los típicas fuentes de hoyos |
1120 fijo para cadenas constituyen los tÃpicas fuentes de hoyos |
1121 explotables que pueden llegar a oscuros errores. Si definitivamente |
1121 explotables que pueden llegar a oscuros errores. Si definitivamente |
1122 debes usar buffers de tamaño fijo para cadenas, usa la función |
1122 debes usar buffers de tamaño fijo para cadenas, usa la función |
1123 <function>g_snprintf()</function> para especificar el tamaño |
1123 <function>g_snprintf()</function> para especificar el tamaño |
1124 máximo del buffer. |
1124 máximo del buffer. |
1125 </para> |
1125 </para> |
1126 |
1126 |
1127 <para> |
1127 <para> |
1128 Glib proporciona la, muy conveniente, función |
1128 Glib proporciona la, muy conveniente, función |
1129 <function>g_strdup_printf()</function>, la cual funciona como |
1129 <function>g_strdup_printf()</function>, la cual funciona como |
1130 <function>sprintf()</function> pero automáticamente |
1130 <function>sprintf()</function> pero automáticamente |
1131 localizará un buffer con el tamaño correcto. El valor de retorno |
1131 localizará un buffer con el tamaño correcto. El valor de retorno |
1132 de esta función debiera ser liberada usando |
1132 de esta función debiera ser liberada usando |
1133 <function>g_free()</function>. A menudo es más conveniente de |
1133 <function>g_free()</function>. A menudo es más conveniente de |
1134 usar que <function>g_snprintf()</function>, ya que esta no |
1134 usar que <function>g_snprintf()</function>, ya que esta no |
1135 limita el tamaño de las cadenas que un programa puede manipular. |
1135 limita el tamaño de las cadenas que un programa puede manipular. |
1136 </para> |
1136 </para> |
1137 |
1137 |
1138 <para> |
1138 <para> |
1139 Si deseas concatenar un grupo de cadenas, puedes usar la función |
1139 Si deseas concatenar un grupo de cadenas, puedes usar la función |
1140 <function>g_strconcat()</function>, la cual recibe una lista |
1140 <function>g_strconcat()</function>, la cual recibe una lista |
1141 variable de cadenas y un puntero a <symbol>NULL</symbol> |
1141 variable de cadenas y un puntero a <symbol>NULL</symbol> |
1142 como último argumento. |
1142 como último argumento. |
1143 </para> |
1143 </para> |
1144 |
1144 |
1145 <para> |
1145 <para> |
1146 <emphasis>Bajo ninguna circunstancia</emphasis> crees un |
1146 <emphasis>Bajo ninguna circunstancia</emphasis> crees un |
1147 programa GTK+ con setuid root. Las bibliotecas de GTK+ y |
1147 programa GTK+ con setuid root. Las bibliotecas de GTK+ y |
1148 GNOME son grandes y complejas y no han tenido auditorías |
1148 GNOME son grandes y complejas y no han tenido auditorÃas |
1149 de seguridad. En cualquier caso, no debieras querer que |
1149 de seguridad. En cualquier caso, no debieras querer que |
1150 una pieza tan grande código sea setuid root. Si definitivamente |
1150 una pieza tan grande código sea setuid root. Si definitivamente |
1151 requieres usar privilegios de root para algo, escribe un |
1151 requieres usar privilegios de root para algo, escribe un |
1152 programa que sea la interfaz de usuario como un proceso |
1152 programa que sea la interfaz de usuario como un proceso |
1153 normal, sin privilegios y crea un programa nexo que |
1153 normal, sin privilegios y crea un programa nexo que |
1154 tenga setuid y se encargue de realizar la operaciones |
1154 tenga setuid y se encargue de realizar la operaciones |
1155 «peligrosas». Además, notifica a las listas |
1155 «peligrosas». Además, notifica a las listas |
1156 de correo de desarrollo de GNOME indicando que requieres |
1156 de correo de desarrollo de GNOME indicando que requieres |
1157 que alguien realice una auditoría de seguridad a tu |
1157 que alguien realice una auditorÃa de seguridad a tu |
1158 programa nexo. |
1158 programa nexo. |
1159 </para> |
1159 </para> |
1160 |
1160 |
1161 <para> |
1161 <para> |
1162 En general, si no estás seguro si puedes crear un riesgo de |
1162 En general, si no estás seguro si puedes crear un riesgo de |
1163 seguridad, pregunte en las listas de correo de desarrollo |
1163 seguridad, pregunte en las listas de correo de desarrollo |
1164 de GNOME. |
1164 de GNOME. |
1165 </para> |
1165 </para> |
1166 |
1166 |
1167 <para> |
1167 <para> |
1168 Puedes leer más sobre temas de seguridad que debieras encontrar |
1168 Puedes leer más sobre temas de seguridad que debieras encontrar |
1169 cuando programes una aplicación Unix en el documento |
1169 cuando programes una aplicación Unix en el documento |
1170 <ulink URL="http://www.fish.com/security/murphy.html">«Murphy's |
1170 <ulink URL="http://www.fish.com/security/murphy.html">«Murphy's |
1171 Law and Computer Security»</ulink>, de Wietse Wenema. |
1171 Law and Computer Security»</ulink>, de Wietse Wenema. |
1172 Hay otros documentos de seguridad en <ulink |
1172 Hay otros documentos de seguridad en <ulink |
1173 URL="http://www.fish.com/security">el sitio fish.com</ulink> |
1173 URL="http://www.fish.com/security">el sitio fish.com</ulink> |
1174 que podrías encontrar interesante. |
1174 que podrÃas encontrar interesante. |
1175 </para> |
1175 </para> |
1176 |
1176 |
1177 <para> |
1177 <para> |
1178 Puedes encontrar muchas otras guías útiles para escribir programas |
1178 Puedes encontrar muchas otras guÃas útiles para escribir programas |
1179 seguros en <ulink |
1179 seguros en <ulink |
1180 url="http://www.dwheeler.com/secure-programs">«Secure |
1180 url="http://www.dwheeler.com/secure-programs">«Secure |
1181 Programming for Linux and Unix HOWTO»</ulink>. |
1181 Programming for Linux and Unix HOWTO»</ulink>. |
1182 </para> |
1182 </para> |
1183 </sect1> |
1183 </sect1> |
1184 |
1184 |
1185 <!-- Performace --> |
1185 <!-- Performace --> |
1186 |
1186 |
1187 <sect1 id="performance"> |
1187 <sect1 id="performance"> |
1188 <title>Rendimiento</title> |
1188 <title>Rendimiento</title> |
1189 |
1189 |
1190 <para> |
1190 <para> |
1191 No leas esta sección hasta que estés seguro que tu programa está |
1191 No leas esta sección hasta que estés seguro que tu programa está |
1192 correcto, por ejemplo, cuando estés seguro que funciona |
1192 correcto, por ejemplo, cuando estés seguro que funciona |
1193 correctamente y no tiene errores. Es más importante que |
1193 correctamente y no tiene errores. Es más importante que |
1194 el código sea correcto a que sea rápido. Un programa lento |
1194 el código sea correcto a que sea rápido. Un programa lento |
1195 pero correcto es mucho mejor a uno rápido pero con errores. |
1195 pero correcto es mucho mejor a uno rápido pero con errores. |
1196 </para> |
1196 </para> |
1197 |
1197 |
1198 <para> |
1198 <para> |
1199 Si quieres optimizar tu programa, el primer paso es determinar |
1199 Si quieres optimizar tu programa, el primer paso es determinar |
1200 un perfil al programa ejecutándolo con datos de la vida real |
1200 un perfil al programa ejecutándolo con datos de la vida real |
1201 y recopilar puntos calientes que requieran optimización. |
1201 y recopilar puntos calientes que requieran optimización. |
1202 Esto ayudará a determinar los lugares que necesitan optimizarse. |
1202 Esto ayudará a determinar los lugares que necesitan optimizarse. |
1203 Es importante que nunca adelantes la optimización si no tienes |
1203 Es importante que nunca adelantes la optimización si no tienes |
1204 una idea clara sobre donde está el problema. Podrías terminar |
1204 una idea clara sobre donde está el problema. PodrÃas terminar |
1205 perdiendo el tiempo en agilizar una rutina que no es la causa |
1205 perdiendo el tiempo en agilizar una rutina que no es la causa |
1206 del cuello de boteLla y como resultado podrías terminar ofuscando |
1206 del cuello de boteLla y como resultado podrÃas terminar ofuscando |
1207 dicha rutina. Esto podría reducir la legibilidad y mantenibilidad |
1207 dicha rutina. Esto podrÃa reducir la legibilidad y mantenibilidad |
1208 del código sin ganancia visible en velocidad. |
1208 del código sin ganancia visible en velocidad. |
1209 </para> |
1209 </para> |
1210 |
1210 |
1211 <para> |
1211 <para> |
1212 Un código sencillo es bueno porque es fácil de entender y |
1212 Un código sencillo es bueno porque es fácil de entender y |
1213 mantener. Si puedes escribir código simple que además sea |
1213 mantener. Si puedes escribir código simple que además sea |
1214 potente y rápido, tanto mejor. Si tienes un trozo de código |
1214 potente y rápido, tanto mejor. Si tienes un trozo de código |
1215 inteligente pero que no es fácil de seguir, entonces documéntalo |
1215 inteligente pero que no es fácil de seguir, entonces documéntalo |
1216 para que las personas no lo estropeen accidentalmente. |
1216 para que las personas no lo estropeen accidentalmente. |
1217 </para> |
1217 </para> |
1218 |
1218 |
1219 <para> |
1219 <para> |
1220 No escribas código que sea difícil de leer y mantener por el |
1220 No escribas código que sea difÃcil de leer y mantener por el |
1221 sólo hecho de hacerlo más rápido. En cambio, prefiere un algoritmo |
1221 sólo hecho de hacerlo más rápido. En cambio, prefiere un algoritmo |
1222 agradable y claro e impleméntalo claramente. |
1222 agradable y claro e impleméntalo claramente. |
1223 </para> |
1223 </para> |
1224 |
1224 |
1225 <para> |
1225 <para> |
1226 Hacer un buen trabajo en el caso general es a menudo mejor que |
1226 Hacer un buen trabajo en el caso general es a menudo mejor que |
1227 tener muchos casos especiales. Sólo provee casos especiales |
1227 tener muchos casos especiales. Sólo provee casos especiales |
1228 cuando se han identificado puntos débiles en el programa. |
1228 cuando se han identificado puntos débiles en el programa. |
1229 </para> |
1229 </para> |
1230 |
1230 |
1231 <!-- List Management in Glib --> |
1231 <!-- List Management in Glib --> |
1232 |
1232 |
1233 <sect2 id="list"> |
1233 <sect2 id="list"> |
1234 <title>Administración de listas en Glib</title> |
1234 <title>Administración de listas en Glib</title> |
1235 <para> |
1235 <para> |
1236 Evita emplear construcciones que terminen ralentizando |
1236 Evita emplear construcciones que terminen ralentizando |
1237 los algoritmos. Si usas |
1237 los algoritmos. Si usas |
1238 <function>g_list_insert_sorted()</function> o |
1238 <function>g_list_insert_sorted()</function> o |
1239 <function>g_list_append()</function> sin ningún cuidado, |
1239 <function>g_list_append()</function> sin ningún cuidado, |
1240 fácilmente puedes tener un algoritmo que se ejecuta en |
1240 fácilmente puedes tener un algoritmo que se ejecuta en |
1241 tiempo proporcional a O(n<superscript>2</superscript>). |
1241 tiempo proporcional a O(n<superscript>2</superscript>). |
1242 Normalmente puedes crear listas hacia atrás, usando |
1242 Normalmente puedes crear listas hacia atrás, usando |
1243 <function>g_list_prepend()</function>, e invirtiéndola |
1243 <function>g_list_prepend()</function>, e invirtiéndola |
1244 cuando hayas terminado usando |
1244 cuando hayas terminado usando |
1245 <function>g_list_reverse()</function>. Esta es una |
1245 <function>g_list_reverse()</function>. Esta es una |
1246 operación O(n). Y si necesitas una lista ordenada, puedes |
1246 operación O(n). Y si necesitas una lista ordenada, puedes |
1247 crearla de la misma forma (hacia atrás) y una vez terminado, |
1247 crearla de la misma forma (hacia atrás) y una vez terminado, |
1248 usar <function>g_list_sort()</function>. |
1248 usar <function>g_list_sort()</function>. |
1249 </para> |
1249 </para> |
1250 |
1250 |
1251 <para> |
1251 <para> |
1252 Si necesitas una lista ordenada en todo momento, puede ser |
1252 Si necesitas una lista ordenada en todo momento, puede ser |
1253 mejor emplear un estructura de árbol o un híbrido |
1253 mejor emplear un estructura de árbol o un hÃbrido |
1254 lista/árbol. Si necesitas construir una lista añadiendo |
1254 lista/árbol. Si necesitas construir una lista añadiendo |
1255 nodos a ella, mantén un puntero al final de la lista |
1255 nodos a ella, mantén un puntero al final de la lista |
1256 y ve cambiándola según sea apropiado; esto te permitirá |
1256 y ve cambiándola según sea apropiado; esto te permitirá |
1257 insertar un nodo al inicio o al final en un tiempo constante. |
1257 insertar un nodo al inicio o al final en un tiempo constante. |
1258 </para> |
1258 </para> |
1259 </sect2> |
1259 </sect2> |
1260 </sect1> |
1260 </sect1> |
1261 |
1261 |
1262 <!-- Localization --> |
1262 <!-- Localization --> |
1263 |
1263 |
1264 <sect1 id="l10n"> |
1264 <sect1 id="l10n"> |
1265 <title>Localización</title> |
1265 <title>Localización</title> |
1266 |
1266 |
1267 <para> |
1267 <para> |
1268 Se pretende que GNOME pueda ejecutarse en distintas localidades |
1268 Se pretende que GNOME pueda ejecutarse en distintas localidades |
1269 y lenguajes, y los programas debieran tener esto en cuenta. No |
1269 y lenguajes, y los programas debieran tener esto en cuenta. No |
1270 tienes que localizar los programas, sólo debes permitir que éstos |
1270 tienes que localizar los programas, sólo debes permitir que éstos |
1271 sean traducibles y localizables. |
1271 sean traducibles y localizables. |
1272 </para> |
1272 </para> |
1273 |
1273 |
1274 <para> |
1274 <para> |
1275 Debes recordar que los diferentes idiomas humanos tienen diferentes |
1275 Debes recordar que los diferentes idiomas humanos tienen diferentes |
1276 gramáticas, así que no debieras suponer la forma de estructurar |
1276 gramáticas, asà que no debieras suponer la forma de estructurar |
1277 cada frase. Esto es importante, por ejemplo, cuando se |
1277 cada frase. Esto es importante, por ejemplo, cuando se |
1278 construyen cadenas a partir de trozos separados. |
1278 construyen cadenas a partir de trozos separados. |
1279 </para> |
1279 </para> |
1280 |
1280 |
1281 <para> |
1281 <para> |
1282 La concatenación normalmente no es la forma correcta de construir |
1282 La concatenación normalmente no es la forma correcta de construir |
1283 una cadena para que sea presentada al usuario. Normalmente terminan |
1283 una cadena para que sea presentada al usuario. Normalmente terminan |
1284 en mensajes que no pueden ser traducidos correctamente en todos |
1284 en mensajes que no pueden ser traducidos correctamente en todos |
1285 los idiomas. En vez de concatenar, intenta usar |
1285 los idiomas. En vez de concatenar, intenta usar |
1286 <function>g_strdup_printf()</function>, por ejemplo: |
1286 <function>g_strdup_printf()</function>, por ejemplo: |
1287 |
1287 |
1345 <title>Compatibilidad binaria en las bibliotecas</title> |
1345 <title>Compatibilidad binaria en las bibliotecas</title> |
1346 |
1346 |
1347 <para> |
1347 <para> |
1348 Para bibliotecas estables y ya liberadas, es muy importante |
1348 Para bibliotecas estables y ya liberadas, es muy importante |
1349 intentar preservar la compatibilidad binaria en las revisiones |
1349 intentar preservar la compatibilidad binaria en las revisiones |
1350 mayores del código. Los desarrolladores de bibliotecas deben |
1350 mayores del código. Los desarrolladores de bibliotecas deben |
1351 intentar no alienar a los usuarios realizando de forma frecuente |
1351 intentar no alienar a los usuarios realizando de forma frecuente |
1352 cambios que sean binariamente incompatibles en bibliotecas que |
1352 cambios que sean binariamente incompatibles en bibliotecas que |
1353 son de producción. Por supuesto, en aquellas bibliotecas que se |
1353 son de producción. Por supuesto, en aquellas bibliotecas que se |
1354 encuentran en desarrollo o están etiquetadas como no finalizadas |
1354 encuentran en desarrollo o están etiquetadas como no finalizadas |
1355 puedes realizar tantos cambios como se necesiten. |
1355 puedes realizar tantos cambios como se necesiten. |
1356 </para> |
1356 </para> |
1357 |
1357 |
1358 <para> |
1358 <para> |
1359 Una biblioteca típicamente exporta un número de interfaces. Estas |
1359 Una biblioteca tÃpicamente exporta un número de interfaces. Estas |
1360 incluyen nombres de rutinas, las firmas o prototipos de estas |
1360 incluyen nombres de rutinas, las firmas o prototipos de estas |
1361 rutinas, variables globales, estructuras, campos de estructura |
1361 rutinas, variables globales, estructuras, campos de estructura |
1362 (tanto los tipos como su significado), el significado de los |
1362 (tanto los tipos como su significado), el significado de los |
1363 valores enumerados y la semántica de los archivos que la |
1363 valores enumerados y la semántica de los archivos que la |
1364 biblioteca crea. Mantener compatibilidad binaria significa que |
1364 biblioteca crea. Mantener compatibilidad binaria significa que |
1365 estas interfaces no cambiarán. Puedes añadir nuevas interfaces |
1365 estas interfaces no cambiarán. Puedes añadir nuevas interfaces |
1366 sin romper la compatibilidad binaria, pero no puedes cambiar |
1366 sin romper la compatibilidad binaria, pero no puedes cambiar |
1367 las ya existentes, ya que los programas antiguos no se ejecutarán |
1367 las ya existentes, ya que los programas antiguos no se ejecutarán |
1368 correctamente. |
1368 correctamente. |
1369 </para> |
1369 </para> |
1370 |
1370 |
1371 <para> |
1371 <para> |
1372 Esta sección incluye un número de ideas acerca de como lograr |
1372 Esta sección incluye un número de ideas acerca de como lograr |
1373 que el código de una biblioteca sea compatible con sus |
1373 que el código de una biblioteca sea compatible con sus |
1374 versiones anteriores. |
1374 versiones anteriores. |
1375 </para> |
1375 </para> |
1376 |
1376 |
1377 <para> |
1377 <para> |
1378 Mantener la compatibilidad binaria significa que los programas |
1378 Mantener la compatibilidad binaria significa que los programas |
1379 y archivos objetos que fueron compilados con una versión |
1379 y archivos objetos que fueron compilados con una versión |
1380 previa del código continuarán funcionando sin recompilar aún |
1380 previa del código continuarán funcionando sin recompilar aún |
1381 cuando la biblioteca sea reemplazada. Es posible encontrar |
1381 cuando la biblioteca sea reemplazada. Es posible encontrar |
1382 una descripción detallada en el nodo info |
1382 una descripción detallada en el nodo info |
1383 <filename>(libtool)Interfaces</filename> de la documentación |
1383 <filename>(libtool)Interfaces</filename> de la documentación |
1384 de GNU libtool. |
1384 de GNU libtool. |
1385 </para> |
1385 </para> |
1386 |
1386 |
1387 <!-- Private Information in Structures --> |
1387 <!-- Private Information in Structures --> |
1388 |
1388 |
1389 <sect2 id="private"> |
1389 <sect2 id="private"> |
1390 <title>Información privada en las estructuras</title> |
1390 <title>Información privada en las estructuras</title> |
1391 |
1391 |
1392 <para> |
1392 <para> |
1393 En el sistema GNOME es una tarea muy común crear un |
1393 En el sistema GNOME es una tarea muy común crear un |
1394 nuevo <structname>GtkObject</structname> para crear |
1394 nuevo <structname>GtkObject</structname> para crear |
1395 una estructura cuyo primer miembro corresponde a la |
1395 una estructura cuyo primer miembro corresponde a la |
1396 clase de la cual hereda este objeto y posteriormente |
1396 clase de la cual hereda este objeto y posteriormente |
1397 un número de variables de instancia que se añaden |
1397 un número de variables de instancia que se añaden |
1398 después del primer miembro. |
1398 después del primer miembro. |
1399 </para> |
1399 </para> |
1400 |
1400 |
1401 <para> |
1401 <para> |
1402 Este esquema de diseño normalmente lleva a que el código |
1402 Este esquema de diseño normalmente lleva a que el código |
1403 sea difícil de actualizar y cambiar: si se quiere |
1403 sea difÃcil de actualizar y cambiar: si se quiere |
1404 extender un objeto donde se necesita mantener su estado |
1404 extender un objeto donde se necesita mantener su estado |
1405 interno, los programadores necesitan recurrir a varios |
1405 interno, los programadores necesitan recurrir a varios |
1406 hacks para mantener el mismo tamaño de las estructuras. |
1406 hacks para mantener el mismo tamaño de las estructuras. |
1407 Esto hace difícil agregar nuevos campos a las estructuras |
1407 Esto hace difÃcil agregar nuevos campos a las estructuras |
1408 públicas sin romper la compatibilidad binaria, ya que |
1408 públicas sin romper la compatibilidad binaria, ya que |
1409 los campos de la estructura pueden cambiar y el tamaño |
1409 los campos de la estructura pueden cambiar y el tamaño |
1410 de las estructuras pueden variar. |
1410 de las estructuras pueden variar. |
1411 </para> |
1411 </para> |
1412 |
1412 |
1413 <para> |
1413 <para> |
1414 Por consiguiente, se sugiere una estrategia que puedan |
1414 Por consiguiente, se sugiere una estrategia que puedan |
1415 adoptar los desarrolladores en el momento de crear nuevos |
1415 adoptar los desarrolladores en el momento de crear nuevos |
1416 objetos. Esta estrategia asegurará la compatibilidad |
1416 objetos. Esta estrategia asegurará la compatibilidad |
1417 binaria y al mismo tiempo mejorará la legibilidad y |
1417 binaria y al mismo tiempo mejorará la legibilidad y |
1418 mantenibilidad del código. |
1418 mantenibilidad del código. |
1419 </para> |
1419 </para> |
1420 |
1420 |
1421 <para> |
1421 <para> |
1422 La idea es que, para un objeto dado, el programador |
1422 La idea es que, para un objeto dado, el programador |
1423 debiera crear tres archivos: el primero que contiene |
1423 debiera crear tres archivos: el primero que contiene |
1424 el contrato entre la biblioteca y el usuario (esto |
1424 el contrato entre la biblioteca y el usuario (esto |
1425 es el archivo de encabezado que se instala en el |
1425 es el archivo de encabezado que se instala en el |
1426 sistema); el segundo contiene la implementación del |
1426 sistema); el segundo contiene la implementación del |
1427 objeto; y el tercer archivo contiene la definición |
1427 objeto; y el tercer archivo contiene la definición |
1428 de la estructura para los campos privados o internos |
1428 de la estructura para los campos privados o internos |
1429 que no necesitan estar en la estructura pública. |
1429 que no necesitan estar en la estructura pública. |
1430 </para> |
1430 </para> |
1431 |
1431 |
1432 <para> |
1432 <para> |
1433 La API pública de la estructura podría incluir un |
1433 La API pública de la estructura podrÃa incluir un |
1434 puntero a un elemento privado, el cual podría |
1434 puntero a un elemento privado, el cual podrÃa |
1435 apuntar a los datos privado de la instancia. Las |
1435 apuntar a los datos privado de la instancia. Las |
1436 rutinas de implementación podría dereferenciar |
1436 rutinas de implementación podrÃa dereferenciar |
1437 este punto para acceder a los datos privados; por |
1437 este punto para acceder a los datos privados; por |
1438 supuesto, el puntero apunta a la estructura que se |
1438 supuesto, el puntero apunta a la estructura que se |
1439 localiza privadamente. |
1439 localiza privadamente. |
1440 </para> |
1440 </para> |
1441 |
1441 |
1442 <para> |
1442 <para> |
1443 Por ejemplo, imagina que se crea el objeto GnomeFrob. |
1443 Por ejemplo, imagina que se crea el objeto GnomeFrob. |
1444 La implementación del widget será dividido en tres |
1444 La implementación del widget será dividido en tres |
1445 archivos: |
1445 archivos: |
1446 |
1446 |
1447 <table> |
1447 <table> |
1448 <title>Archivos que muestran el widget de ejemplo |
1448 <title>Archivos que muestran el widget de ejemplo |
1449 GnomeFrob</title> |
1449 GnomeFrob</title> |
1518 |
1518 |
1519 frob->priv->frobbed = TRUE; |
1519 frob->priv->frobbed = TRUE; |
1520 }</programlisting> |
1520 }</programlisting> |
1521 </example> |
1521 </example> |
1522 |
1522 |
1523 Fíjese en el uso de prototipos de estructura: esto permite que |
1523 FÃjese en el uso de prototipos de estructura: esto permite que |
1524 el compilador realice más verificaciones en tiempo de |
1524 el compilador realice más verificaciones en tiempo de |
1525 compilación respecto a los tipos que estan siendo empleados. |
1525 compilación respecto a los tipos que estan siendo empleados. |
1526 </para> |
1526 </para> |
1527 |
1527 |
1528 <para> |
1528 <para> |
1529 Este esquema es útil en algunas situaciones, particularmente |
1529 Este esquema es útil en algunas situaciones, particularmente |
1530 en el caso en el cual vale la pena almacenar un puntero |
1530 en el caso en el cual vale la pena almacenar un puntero |
1531 extra para una instancia del objeto. Si esto no fuera |
1531 extra para una instancia del objeto. Si esto no fuera |
1532 posible, el programador necesitaría recurrir a otros |
1532 posible, el programador necesitarÃa recurrir a otros |
1533 artilugios para evitar este problema. |
1533 artilugios para evitar este problema. |
1534 </para> |
1534 </para> |
1535 |
1535 |
1536 <para> |
1536 <para> |
1537 El propósito de tener un archivo de encabezado privado |
1537 El propósito de tener un archivo de encabezado privado |
1538 extra para las estructuras privadas es permitir que las |
1538 extra para las estructuras privadas es permitir que las |
1539 clases derivadas usen esta información. Por supuesto, |
1539 clases derivadas usen esta información. Por supuesto, |
1540 una buena práctica de programación indicaría que debiera |
1540 una buena práctica de programación indicarÃa que debiera |
1541 proveerse de interfaces o métodos de acceso precisamente |
1541 proveerse de interfaces o métodos de acceso precisamente |
1542 para que el programador no tenga que lidiar con |
1542 para que el programador no tenga que lidiar con |
1543 estructuras privadas. Se debiera intentar alcanzar un |
1543 estructuras privadas. Se debiera intentar alcanzar un |
1544 balance entre buena práctica y pragmatismo cuando se |
1544 balance entre buena práctica y pragmatismo cuando se |
1545 crean estructuras privadas y métodos de acceso públicos. |
1545 crean estructuras privadas y métodos de acceso públicos. |
1546 </para> |
1546 </para> |
1547 |
1547 |
1548 <para> |
1548 <para> |
1549 Podrían aparecer algunos problemas, por ejemplo, cuando |
1549 PodrÃan aparecer algunos problemas, por ejemplo, cuando |
1550 se ha enviado un versión del código y que está siendo |
1550 se ha enviado un versión del código y que está siendo |
1551 ampliamente usado y se desea extenderlo. Hay dos |
1551 ampliamente usado y se desea extenderlo. Hay dos |
1552 soluciones para esto. |
1552 soluciones para esto. |
1553 </para> |
1553 </para> |
1554 |
1554 |
1555 <para> |
1555 <para> |
1556 La primera opción es encontrar un campo puntero en la |
1556 La primera opción es encontrar un campo puntero en la |
1557 estructura pública que pueda hacerse privada y |
1557 estructura pública que pueda hacerse privada y |
1558 reemplazar el puntero a la parte privada de la |
1558 reemplazar el puntero a la parte privada de la |
1559 estructura. Esto preserva el tamaño de la estructura |
1559 estructura. Esto preserva el tamaño de la estructura |
1560 ya que, para los propósitos de GNOME, se puede |
1560 ya que, para los propósitos de GNOME, se puede |
1561 asumir que los punteros son todos del mismo tamaño. |
1561 asumir que los punteros son todos del mismo tamaño. |
1562 Se puede hacer que este campo apunte a la parte privada |
1562 Se puede hacer que este campo apunte a la parte privada |
1563 de la estructura que será ubicada por la función que |
1563 de la estructura que será ubicada por la función que |
1564 originalmente creaba la estructura pública. Es |
1564 originalmente creaba la estructura pública. Es |
1565 importante que este campo no sea llamado |
1565 importante que este campo no sea llamado |
1566 <structfield>private</structfield>, se trata de |
1566 <structfield>private</structfield>, se trata de |
1567 una palabra reservada de C++ y creará problemas cuando |
1567 una palabra reservada de C++ y creará problemas cuando |
1568 el archivo de encabezado sea usado desde programas |
1568 el archivo de encabezado sea usado desde programas |
1569 fuentes C++ — mejor llámalo |
1569 fuentes C++ — mejor llámalo |
1570 <structfield>priv</structfield>. Por supuesto, este |
1570 <structfield>priv</structfield>. Por supuesto, este |
1571 tipo de cambios sólo funcionará si el antiguo campo |
1571 tipo de cambios sólo funcionará si el antiguo campo |
1572 puntero solamente era usado para propósitos internos; |
1572 puntero solamente era usado para propósitos internos; |
1573 si los usuarios de la biblioteca habían tenido acceso |
1573 si los usuarios de la biblioteca habÃan tenido acceso |
1574 a dicho campo para cualquier propósito, será necesario |
1574 a dicho campo para cualquier propósito, será necesario |
1575 buscar otro campo o buscar una solución diferente. |
1575 buscar otro campo o buscar una solución diferente. |
1576 </para> |
1576 </para> |
1577 |
1577 |
1578 <para> |
1578 <para> |
1579 Si la estructura original fue derivada de |
1579 Si la estructura original fue derivada de |
1580 <structname>GtkObject</structname> y no hay campos punteros |
1580 <structname>GtkObject</structname> y no hay campos punteros |
1581 que puedan ser reemplazados, puedes usar la facilidad |
1581 que puedan ser reemplazados, puedes usar la facilidad |
1582 de datos de objetos de GTK+. Esto permite asociar punteros |
1582 de datos de objetos de GTK+. Esto permite asociar punteros |
1583 a datos arbitrarios a objetos. Usa la función |
1583 a datos arbitrarios a objetos. Usa la función |
1584 <function>gtk_object_set_data()</function> para adjuntar |
1584 <function>gtk_object_set_data()</function> para adjuntar |
1585 valores o estructuras a un objeto y cuando requieras usarlos |
1585 valores o estructuras a un objeto y cuando requieras usarlos |
1586 la función <function>gtk_object_get_data()</function> |
1586 la función <function>gtk_object_get_data()</function> |
1587 permitirá recuperar dichos valores. Esto puede ser empleado |
1587 permitirá recuperar dichos valores. Esto puede ser empleado |
1588 para adjuntar una estructura privada a un objeto GTK+. |
1588 para adjuntar una estructura privada a un objeto GTK+. |
1589 Esto no es tan eficiente como el enfoque anterior, pero podría |
1589 Esto no es tan eficiente como el enfoque anterior, pero podrÃa |
1590 no importar para el dominio particular de la aplicación. Si |
1590 no importar para el dominio particular de la aplicación. Si |
1591 los datos serán accedidos frecuentemente, se pueden usar |
1591 los datos serán accedidos frecuentemente, se pueden usar |
1592 quarks en vez de cadenas para agregar y obtenerlos a través |
1592 quarks en vez de cadenas para agregar y obtenerlos a través |
1593 de las funciones |
1593 de las funciones |
1594 <function>gtk_object_set_data_by_id()</function> y |
1594 <function>gtk_object_set_data_by_id()</function> y |
1595 <function>gtk_object_get_data_by_id()</function>, |
1595 <function>gtk_object_get_data_by_id()</function>, |
1596 respectivamente. |
1596 respectivamente. |
1597 </para> |
1597 </para> |
1736 |
1736 |
1737 * baz.c (ugly_function): Beautified by using a helper function.</programlisting> |
1737 * baz.c (ugly_function): Beautified by using a helper function.</programlisting> |
1738 </para> |
1738 </para> |
1739 |
1739 |
1740 <para> |
1740 <para> |
1741 Si agregas una nueva función a una biblioteca, escribe |
1741 Si agregas una nueva función a una biblioteca, escribe |
1742 la referencia necesaria y la documentación de programación. |
1742 la referencia necesaria y la documentación de programación. |
1743 Puedes escribir una referencia a la documentacion |
1743 Puedes escribir una referencia a la documentacion |
1744 en línea usando el formato de comentarios descrito en |
1744 en lÃnea usando el formato de comentarios descrito en |
1745 <filename>gnome-libs/devel-docs/api-comment-style.txt</filename>. |
1745 <filename>gnome-libs/devel-docs/api-comment-style.txt</filename>. |
1746 Si usas &Emacs;, |
1746 Si usas &Emacs;, |
1747 <filename>gnome-libs/tools/gnome-doc/gnome-doc.el</filename> |
1747 <filename>gnome-libs/tools/gnome-doc/gnome-doc.el</filename> |
1748 provee un acelerador que puede ser empleado para añadir |
1748 provee un acelerador que puede ser empleado para añadir |
1749 una plantilla de documentación al programa. |
1749 una plantilla de documentación al programa. |
1750 </para> |
1750 </para> |
1751 </sect2> |
1751 </sect2> |
1752 |
1752 |
1753 <!-- Changing Code on CVS --> |
1753 <!-- Changing Code on CVS --> |
1754 |
1754 |
1755 <sect2 id="change-cvs"> |
1755 <sect2 id="change-cvs"> |
1756 <title>Cómo actualizar en CVS</title> |
1756 <title>Cómo actualizar en CVS</title> |
1757 |
1757 |
1758 <para> |
1758 <para> |
1759 Si tienes acceso de escritura en el repositorio CVS de GNOME, |
1759 Si tienes acceso de escritura en el repositorio CVS de GNOME, |
1760 debes seguir algunas políticas adicionales. Ya que estás |
1760 debes seguir algunas polÃticas adicionales. Ya que estás |
1761 trabajando en la copia maestra de los fuentes, debes tener |
1761 trabajando en la copia maestra de los fuentes, debes tener |
1762 especial cuidado. |
1762 especial cuidado. |
1763 </para> |
1763 </para> |
1764 |
1764 |
1765 <para> |
1765 <para> |
1766 Si estás reparando algo en un programa que está en el CVS |
1766 Si estás reparando algo en un programa que está en el CVS |
1767 o si estás añadiendo una funcionalidad allí, y si no has |
1767 o si estás añadiendo una funcionalidad allÃ, y si no has |
1768 estado trabajando en dicho programa por un período largo |
1768 estado trabajando en dicho programa por un perÃodo largo |
1769 de tiempo, pregunta al autor original antes de aplicar |
1769 de tiempo, pregunta al autor original antes de aplicar |
1770 sus parches. Generalmente está bien formular estas |
1770 sus parches. Generalmente está bien formular estas |
1771 preguntas en la lista de correo |
1771 preguntas en la lista de correo |
1772 <filename>gnome-devel-list</filename>. |
1772 <filename>gnome-devel-list</filename>. |
1773 </para> |
1773 </para> |
1774 |
1774 |
1775 <para> |
1775 <para> |
1776 Una vez que el autor del programa te indique como un |
1776 Una vez que el autor del programa te indique como un |
1777 ‘contribuyente frecuente’, puedes comenzar |
1777 ‘contribuyente frecuente’, puedes comenzar |
1778 aplicar los parches sin previo consentimiento. Si |
1778 aplicar los parches sin previo consentimiento. Si |
1779 quieres aplicar una reorganización mayor del código, |
1779 quieres aplicar una reorganización mayor del código, |
1780 debieras preguntar primero. |
1780 debieras preguntar primero. |
1781 </para> |
1781 </para> |
1782 |
1782 |
1783 <para> |
1783 <para> |
1784 Algunos módulos en el CVS tienen rama estable y de |
1784 Algunos módulos en el CVS tienen rama estable y de |
1785 desarrollo. Normalmente el desarrollo debiera ir |
1785 desarrollo. Normalmente el desarrollo debiera ir |
1786 en la rama HEAD en el CVS, y la rama estable debiera |
1786 en la rama HEAD en el CVS, y la rama estable debiera |
1787 mantenerse separadamente. Generalmente no se añaden |
1787 mantenerse separadamente. Generalmente no se añaden |
1788 nuevas características a las rama estable; sólo |
1788 nuevas caracterÃsticas a las rama estable; sólo |
1789 se reparan errores. Repara el error a la rama estable |
1789 se reparan errores. Repara el error a la rama estable |
1790 y pregunta al autor principal sobre la política para |
1790 y pregunta al autor principal sobre la polÃtica para |
1791 mezclar parches en la rama de desarrollo; algunos |
1791 mezclar parches en la rama de desarrollo; algunos |
1792 autores prefieren hacerlo por lotes, mientras hay otros |
1792 autores prefieren hacerlo por lotes, mientras hay otros |
1793 que prefieren mezclarlos inmediatamente. |
1793 que prefieren mezclarlos inmediatamente. |
1794 </para> |
1794 </para> |
1795 |
1795 |
1796 <para> |
1796 <para> |
1797 Si trabajas en una característica experimental que |
1797 Si trabajas en una caracterÃstica experimental que |
1798 podría estropear mucho código, crea una rama en el CVS |
1798 podrÃa estropear mucho código, crea una rama en el CVS |
1799 y realiza los cambios allí. No los mezcles en la rama |
1799 y realiza los cambios allÃ. No los mezcles en la rama |
1800 principal de desarrollo hasta que te encuentres |
1800 principal de desarrollo hasta que te encuentres |
1801 razonablemente seguro que funcionará correctamente y que |
1801 razonablemente seguro que funcionará correctamente y que |
1802 se integrará bien dentro del resto del código. El uso de |
1802 se integrará bien dentro del resto del código. El uso de |
1803 una rama para trabajo en características experimentales |
1803 una rama para trabajo en caracterÃsticas experimentales |
1804 te permitirá evitar interrumpir el trabajo de otros |
1804 te permitirá evitar interrumpir el trabajo de otros |
1805 desarrolladores. Pregunte al autor principal antes de |
1805 desarrolladores. Pregunte al autor principal antes de |
1806 mezclar tu rama y traer sus cambios a la parte principal |
1806 mezclar tu rama y traer sus cambios a la parte principal |
1807 del árbol. |
1807 del árbol. |
1808 </para> |
1808 </para> |
1809 |
1809 |
1810 <para> |
1810 <para> |
1811 Como siempre, agrega un registro en el &ChangeLog; |
1811 Como siempre, agrega un registro en el &ChangeLog; |
1812 cuando realices un cambio. Algunos autores tienen la |
1812 cuando realices un cambio. Algunos autores tienen la |
1813 política de rechazar, correctamente, los cambios que |
1813 polÃtica de rechazar, correctamente, los cambios que |
1814 no tienen tal registro. |
1814 no tienen tal registro. |
1815 </para> |
1815 </para> |
1816 |
1816 |
1817 <para> |
1817 <para> |
1818 Algunas veces existen diferentes políticas para los módulos, |
1818 Algunas veces existen diferentes polÃticas para los módulos, |
1819 verifica si el módulo contiene un archivo |
1819 verifica si el módulo contiene un archivo |
1820 <filename>README.CVS</filename>. Si es así, lee ese archivo |
1820 <filename>README.CVS</filename>. Si es asÃ, lee ese archivo |
1821 antes de realizar cambios. |
1821 antes de realizar cambios. |
1822 </para> |
1822 </para> |
1823 |
1823 |
1824 <!-- Branches and Tags --> |
1824 <!-- Branches and Tags --> |
1825 |
1825 |
1826 <sect3 id="branches"> |
1826 <sect3 id="branches"> |
1827 <title>Ramas y marcas</title> |
1827 <title>Ramas y marcas</title> |
1828 |
1828 |
1829 <para> |
1829 <para> |
1830 Tenemos una convención para nombrar las ramas y marcas o |
1830 Tenemos una convención para nombrar las ramas y marcas o |
1831 puntos de una rama en el repositorio de CVS de GNOME. |
1831 puntos de una rama en el repositorio de CVS de GNOME. |
1832 Las marcas deben ser definidas después que se libera cada |
1832 Las marcas deben ser definidas después que se libera cada |
1833 nueva version y deben ser de la forma |
1833 nueva version y deben ser de la forma |
1834 «MODULE_MAJOR_MINOR_MICRO», por ejemplo, |
1834 «MODULE_MAJOR_MINOR_MICRO», por ejemplo, |
1835 «GNOME_LIBS_1_0_53». Los puntos de una rama |
1835 «GNOME_LIBS_1_0_53». Los puntos de una rama |
1836 deben ser de la forma «MODULE_BRANCH_ANCHOR», |
1836 deben ser de la forma «MODULE_BRANCH_ANCHOR», |
1837 como en «GNOME_LIBS_1_0_ANCHOR». Finalmente, |
1837 como en «GNOME_LIBS_1_0_ANCHOR». Finalmente, |
1838 una rama raíz en este punto debiera ser de la forma |
1838 una rama raÃz en este punto debiera ser de la forma |
1839 «module-branch», por ejemplo, |
1839 «module-branch», por ejemplo, |
1840 «gnome-libs-1-0». Usa esta convención cuando |
1840 «gnome-libs-1-0». Usa esta convención cuando |
1841 crees marcas, puntos de una rama y ramas. |
1841 crees marcas, puntos de una rama y ramas. |
1842 </para> |
1842 </para> |
1843 </sect3> |
1843 </sect3> |
1844 |
1844 |
1845 <!-- Additional CVS Policies --> |
1845 <!-- Additional CVS Policies --> |
1846 |
1846 |
1847 <sect3 id="cvs-policies"> |
1847 <sect3 id="cvs-policies"> |
1848 <title>Políticas adicionales del CVS</title> |
1848 <title>PolÃticas adicionales del CVS</title> |
1849 |
1849 |
1850 <para> |
1850 <para> |
1851 CVS no proporciona un manera preconstruida para renombrar archivos |
1851 CVS no proporciona un manera preconstruida para renombrar archivos |
1852 o moverlos a otros directorios. Debiera planificar |
1852 o moverlos a otros directorios. Debiera planificar |
1853 cuidadosamente el árbol del repositorio de tal forma que evite |
1853 cuidadosamente el árbol del repositorio de tal forma que evite |
1854 mover o renombrar archivos. |
1854 mover o renombrar archivos. |
1855 </para> |
1855 </para> |
1856 |
1856 |
1857 <para> |
1857 <para> |
1858 En el caso que debas mover o renombrar un archivo en el CVS, |
1858 En el caso que debas mover o renombrar un archivo en el CVS, |
1859 <emphasis>NO EJECUTES</emphasis> «cvs remove» |
1859 <emphasis>NO EJECUTES</emphasis> «cvs remove» |
1860 y luego «cvs add». Si lo haces, los archivos |
1860 y luego «cvs add». Si lo haces, los archivos |
1861 «nuevos» perderán la capacidad de seguir su |
1861 «nuevos» perderán la capacidad de seguir su |
1862 historial de cambios, ya que desde el punto de vista de CVS |
1862 historial de cambios, ya que desde el punto de vista de CVS |
1863 serán archivos completamente nuevos en su revisión |
1863 serán archivos completamente nuevos en su revisión |
1864 inicial. Un objetivo del repositorio CVS de GNOME es |
1864 inicial. Un objetivo del repositorio CVS de GNOME es |
1865 poder seguir la historia de los fuentes de manera |
1865 poder seguir la historia de los fuentes de manera |
1866 precisa desde el inicio. |
1866 precisa desde el inicio. |
1867 </para> |
1867 </para> |
1868 |
1868 |
1869 <para> |
1869 <para> |
1870 <emphasis>Por favor</emphasis>, pregunte al mantenedor |
1870 <emphasis>Por favor</emphasis>, pregunte al mantenedor |
1871 del CVS, esto es, una persona conocida con acceso shell |
1871 del CVS, esto es, una persona conocida con acceso shell |
1872 a la máquina con CVS, para realizar la cirugía necesaria |
1872 a la máquina con CVS, para realizar la cirugÃa necesaria |
1873 para mover los archivos por ti. Esto requiere |
1873 para mover los archivos por ti. Esto requiere |
1874 conocimiento de la forma en que funciona CVS y debe ser |
1874 conocimiento de la forma en que funciona CVS y debe ser |
1875 hecho muy cuidadosamente. La recuperación de un error de |
1875 hecho muy cuidadosamente. La recuperación de un error de |
1876 «cvs add/remove» es una tarea muy desagradable; |
1876 «cvs add/remove» es una tarea muy desagradable; |
1877 Si mueves archivo en esta forma equivocada, un mantenedor |
1877 Si mueves archivo en esta forma equivocada, un mantenedor |
1878 del CVS, quien tendrá que ir a reparar y realizar el trabajo |
1878 del CVS, quien tendrá que ir a reparar y realizar el trabajo |
1879 sucio, reclamará las penas del infierno. Así es que mejor |
1879 sucio, reclamará las penas del infierno. Asà es que mejor |
1880 pregunta por una persona que pueda mover los archivos por |
1880 pregunta por una persona que pueda mover los archivos por |
1881 ti. |
1881 ti. |
1882 </para> |
1882 </para> |
1883 </sect3> |
1883 </sect3> |
1884 </sect2> |
1884 </sect2> |
1886 </sect1> |
1886 </sect1> |
1887 |
1887 |
1888 <!-- Maintaining a Package --> |
1888 <!-- Maintaining a Package --> |
1889 |
1889 |
1890 <sect1 id="maintain"> |
1890 <sect1 id="maintain"> |
1891 <title>Cómo mantener un paquete</title> |
1891 <title>Cómo mantener un paquete</title> |
1892 |
1892 |
1893 <para> |
1893 <para> |
1894 Un mantenedor de paquete es una persona que se preocupa de |
1894 Un mantenedor de paquete es una persona que se preocupa de |
1895 liberar versiones, integrar cambios de otras personas y, |
1895 liberar versiones, integrar cambios de otras personas y, |
1896 en general, ser responsable de un paquete. Durante el |
1896 en general, ser responsable de un paquete. Durante el |
1897 período de vida de un paquete, éste puede cambiar de |
1897 perÃodo de vida de un paquete, éste puede cambiar de |
1898 mantenedores, por ejemplo, una persona que pierde interés |
1898 mantenedores, por ejemplo, una persona que pierde interés |
1899 o que ya no puede dedicarle tiempo suficiente como mantenedor. |
1899 o que ya no puede dedicarle tiempo suficiente como mantenedor. |
1900 </para> |
1900 </para> |
1901 |
1901 |
1902 <para> |
1902 <para> |
1903 En conformidad con los Estándares de programación de GNU, GNOME |
1903 En conformidad con los Estándares de programación de GNU, GNOME |
1904 usa GNU Autoconf para manejar la portabilidad y GNU Automake |
1904 usa GNU Autoconf para manejar la portabilidad y GNU Automake |
1905 para crear makefiles. Automake hace especialmente fácil |
1905 para crear makefiles. Automake hace especialmente fácil |
1906 construir paquetes correctos, así que si eres un mantenedor |
1906 construir paquetes correctos, asà que si eres un mantenedor |
1907 de paquetes, debieras aprender como usarlo. Autoconf y |
1907 de paquetes, debieras aprender como usarlo. Autoconf y |
1908 Automake tienen muchas áreas truculentas, así que siéntete |
1908 Automake tienen muchas áreas truculentas, asà que siéntete |
1909 libre de pedir ayuda en las listas de desarrollo de GNOME |
1909 libre de pedir ayuda en las listas de desarrollo de GNOME |
1910 si tienes preguntas sobre la forma correcta de construir |
1910 si tienes preguntas sobre la forma correcta de construir |
1911 makefiles para tu paquete. |
1911 makefiles para tu paquete. |
1912 </para> |
1912 </para> |
1913 |
1913 |
1914 <para> |
1914 <para> |
1915 Un número de personas regularmente contribuye con traducciones |
1915 Un número de personas regularmente contribuye con traducciones |
1916 localizadas de los catálogos de mensajes en los paquetes de |
1916 localizadas de los catálogos de mensajes en los paquetes de |
1917 GNOME. Para mantener las traducciones actualizadas tanto como |
1917 GNOME. Para mantener las traducciones actualizadas tanto como |
1918 sea posible, los mantenedores deben coordinarse con los |
1918 sea posible, los mantenedores deben coordinarse con los |
1919 traductores para que estos últimos puedan actualizar las |
1919 traductores para que estos últimos puedan actualizar las |
1920 traducciones a tiempo cuando se va a liberar una nueva |
1920 traducciones a tiempo cuando se va a liberar una nueva |
1921 versión del paquete. Una buena forma de notificar a los |
1921 versión del paquete. Una buena forma de notificar a los |
1922 traductores consiste en enviar un mensaje a |
1922 traductores consiste en enviar un mensaje a |
1923 <email>gnome-i18n@gnome.org</email> con suficientes |
1923 <email>gnome-i18n@gnome.org</email> con suficientes |
1924 días de anticipación. Esto les permitirá actualizar sus |
1924 dÃas de anticipación. Esto les permitirá actualizar sus |
1925 respectivas traducciones a tiempo para puedan ser incluidas |
1925 respectivas traducciones a tiempo para puedan ser incluidas |
1926 en la siguiente versión liberada. |
1926 en la siguiente versión liberada. |
1927 </para> |
1927 </para> |
1928 </sect1> |
1928 </sect1> |
1929 |
1929 |
1930 <!-- Memory Leaks Agenda --> |
1930 <!-- Memory Leaks Agenda --> |
1931 |
1931 |
1932 <sect1 id="memory-leak"> |
1932 <sect1 id="memory-leak"> |
1933 <title>¿Por qué preocuparse por la pérdida de memoria?</title> |
1933 <title>¿Por qué preocuparse por la pérdida de memoria?</title> |
1934 |
1934 |
1935 <para> |
1935 <para> |
1936 Échale un vistazo a la lista de errores de Mozilla y una cosa es |
1936 Échale un vistazo a la lista de errores de Mozilla y una cosa es |
1937 clara: el nuevo código que entra a Mozilla no es (o no ha sido) |
1937 clara: el nuevo código que entra a Mozilla no es (o no ha sido) |
1938 verificado suficientemente por pérdida de memoria y problemas |
1938 verificado suficientemente por pérdida de memoria y problemas |
1939 de acceso. |
1939 de acceso. |
1940 </para> |
1940 </para> |
1941 |
1941 |
1942 <para> |
1942 <para> |
1943 Las pérdidas de memoria son malas por varias razones: |
1943 Las pérdidas de memoria son malas por varias razones: |
1944 |
1944 |
1945 <itemizedlist> |
1945 <itemizedlist> |
1946 <listitem> |
1946 <listitem> |
1947 <para> |
1947 <para> |
1948 Se comerá el área de intercambio lentamente. A la larga tu |
1948 Se comerá el área de intercambio lentamente. A la larga tu |
1949 programa, o hasta tu máquina sucumbirán. |
1949 programa, o hasta tu máquina sucumbirán. |
1950 </para> |
1950 </para> |
1951 <para> |
1951 <para> |
1952 Nadie quiere que su programa o biblioteca adquiera la |
1952 Nadie quiere que su programa o biblioteca adquiera la |
1953 reputación de ser una porquería sólo porque uno ha sido un |
1953 reputación de ser una porquerÃa sólo porque uno ha sido un |
1954 vago. Déjaselo a las personas en Redmond. |
1954 vago. Déjaselo a las personas en Redmond. |
1955 </para> |
1955 </para> |
1956 </listitem> |
1956 </listitem> |
1957 |
1957 |
1958 <listitem> |
1958 <listitem> |
1959 <para> |
1959 <para> |
1960 Ocultan el mal uso de la memoria. Si olvidas liberar la |
1960 Ocultan el mal uso de la memoria. Si olvidas liberar la |
1961 memoria, no hay forma de atrapar las lecturas y |
1961 memoria, no hay forma de atrapar las lecturas y |
1962 escrituras a esos trozos de memoria. Si, posteriormente, |
1962 escrituras a esos trozos de memoria. Si, posteriormente, |
1963 reparas la pérdida, una parte completamente distinta |
1963 reparas la pérdida, una parte completamente distinta |
1964 del programa podría fallar. |
1964 del programa podrÃa fallar. |
1965 </para> |
1965 </para> |
1966 </listitem> |
1966 </listitem> |
1967 |
1967 |
1968 <listitem> |
1968 <listitem> |
1969 <para> |
1969 <para> |
1970 Cuando se usan verificadores automáticos de memoria, |
1970 Cuando se usan verificadores automáticos de memoria, |
1971 nadie quiere ver 600 problemas, de los cuales 500 |
1971 nadie quiere ver 600 problemas, de los cuales 500 |
1972 se encuentran en las bibliotecas de soporte. Lo que |
1972 se encuentran en las bibliotecas de soporte. Lo que |
1973 deseas saber es que estaba todo limpio antes que comenzara |
1973 deseas saber es que estaba todo limpio antes que comenzara |
1974 el caos, y por lo tanto, esos problemas te corresponde a ti |
1974 el caos, y por lo tanto, esos problemas te corresponde a ti |
1975 arreglarlos. |
1975 arreglarlos. |
1976 </para> |
1976 </para> |
1977 |
1977 |
1978 <para> |
1978 <para> |
1979 Este es uno de los problemas de Mozilla actualmente: |
1979 Este es uno de los problemas de Mozilla actualmente: |
1980 pierde memoria sin parar así que ¿cómo vas a saber si has |
1980 pierde memoria sin parar asà que ¿cómo vas a saber si has |
1981 contribuido al problema? |
1981 contribuido al problema? |
1982 </para> |
1982 </para> |
1983 </listitem> |
1983 </listitem> |
1984 </itemizedlist> |
1984 </itemizedlist> |
1985 </para> |
1985 </para> |
1986 |
1986 |
1987 <sect2 id="memory-advice"> |
1987 <sect2 id="memory-advice"> |
1988 <title>Algunos consejos contra la pérdida de memoria.</title> |
1988 <title>Algunos consejos contra la pérdida de memoria.</title> |
1989 |
1989 |
1990 <para> |
1990 <para> |
1991 <itemizedlist> |
1991 <itemizedlist> |
1992 <listitem> |
1992 <listitem> |
1993 <para> |
1993 <para> |
1994 Usa «<symbol>const</symbol>» donde sea posible (para |
1994 Usa «<symbol>const</symbol>» donde sea posible (para |
1995 punteros obviamente). |
1995 punteros obviamente). |
1996 </para> |
1996 </para> |
1997 <para> |
1997 <para> |
1998 Si un argumento es «<symbol>const</symbol>», entonces |
1998 Si un argumento es «<symbol>const</symbol>», entonces |
1999 indudablemente la función llamada no liberará la memoria por |
1999 indudablemente la función llamada no liberará la memoria por |
2000 ti. |
2000 ti. |
2001 </para> |
2001 </para> |
2002 <para> |
2002 <para> |
2003 Si el tipo de resultado de una función es |
2003 Si el tipo de resultado de una función es |
2004 «<symbol>const</symbol>», entonces |
2004 «<symbol>const</symbol>», entonces |
2005 claramente no eres responsable por liberarlo. |
2005 claramente no eres responsable por liberarlo. |
2006 <emphasis>Probablemente</emphasis> lo será para un resultado |
2006 <emphasis>Probablemente</emphasis> lo será para un resultado |
2007 distinto de «<symbol>const</symbol>» (que no sea un entero |
2007 distinto de «<symbol>const</symbol>» (que no sea un entero |
2008 o algo similar). |
2008 o algo similar). |
2009 </para> |
2009 </para> |
2010 <para> |
2010 <para> |
2011 Fíjate en que, desafortunadamente, esto no funciona muy bien |
2011 FÃjate en que, desafortunadamente, esto no funciona muy bien |
2012 con los objetos que cuentan referencias. Funciona bien |
2012 con los objetos que cuentan referencias. Funciona bien |
2013 con cadenas. |
2013 con cadenas. |
2014 </para> |
2014 </para> |
2015 <para> |
2015 <para> |
2016 Dado que C usa llamadas por valor, no tiene sentido |
2016 Dado que C usa llamadas por valor, no tiene sentido |
2017 aplicar «<symbol>const</symbol>» a tipos |
2017 aplicar «<symbol>const</symbol>» a tipos |
2018 <symbol>int</symbol>, <symbol>double</symbol> y similares. |
2018 <symbol>int</symbol>, <symbol>double</symbol> y similares. |
2019 </para> |
2019 </para> |
2020 </listitem> |
2020 </listitem> |
2021 |
2021 |
2022 <listitem> |
2022 <listitem> |