Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs/sp_SP: Add translation of process/4.Coding.rst

Translate Documentation/process/4.Coding.rst into Spanish.

Co-developed-by: Avadhut Naik <avadhut.naik@amd.com>
Signed-off-by: Avadhut Naik <avadhut.naik@amd.com>
Signed-off-by: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20241129155851.1023884-3-carlos.bilbao.osdev@gmail.com

authored by

Carlos Bilbao and committed by
Jonathan Corbet
ad7f6532 42b5e1e2

+462 -2
+461 -2
Documentation/translations/sp_SP/process/4.Coding.rst
··· 1 1 .. include:: ../disclaimer-sp.rst 2 2 3 3 :Original: Documentation/process/4.Coding.rst 4 + :Translator: Carlos Bilbao <carlos.bilbao.osdev@gmail.com> and Avadhut Naik <avadhut.naik@amd.com> 4 5 5 6 .. _sp_development_coding: 6 7 7 8 Conseguir el código correcto 8 9 ============================ 9 10 10 - .. warning:: 11 - TODO aún no traducido 11 + Si bien hay mucho que decir a favor de un proceso de diseño sólido y 12 + orientado a la comunidad, la prueba de cualquier proyecto de desarrollo del 13 + kernel está en el código resultante. Es el código lo que será examinado por 14 + otros desarrolladores y lo que será incluido (o no) en el árbol principal. 15 + Por lo tanto, es la calidad de este código lo que determinará el éxito 16 + final del proyecto. 17 + 18 + Esta sección examinará el proceso de programación. Comenzaremos observando 19 + algunas de las maneras en que los desarrolladores del kernel pueden cometer 20 + errores. Luego, el enfoque se dirigirá hacia hacer las cosas bien y las 21 + herramientas que pueden ayudar en dicha búsqueda. 22 + 23 + Problemas 24 + --------- 25 + 26 + Estilo de programación 27 + ********************** 28 + 29 + El kernel ha tenido durante mucho tiempo un estilo de programación 30 + estándar, descrito en la documentación del kernel en 31 + `Documentation/process/coding-style.rst`. Durante gran parte de ese tiempo, 32 + las políticas descritas en ese archivo se tomaban como, en el mejor de los 33 + casos, orientativas. Como resultado, hay una cantidad considerable de 34 + código en el kernel que no cumple con las pautas de estilo de programación. 35 + La presencia de ese código lleva a dos peligros independientes para los 36 + desarrolladores del kernel. 37 + 38 + El primero de estos es creer que los estándares de programación del kernel 39 + no importan y no se aplican. La realidad es que agregar nuevo código al 40 + kernel es muy difícil si ese código no está escrito de acuerdo con el 41 + estándar; muchos desarrolladores solicitarán que el código sea reformateado 42 + antes de revisarlo. Una base de código tan grande como el kernel requiere 43 + cierta uniformidad para que los desarrolladores puedan comprender 44 + rápidamente cualquier parte de él. Así que ya no hay lugar para el código 45 + con formato extraño. 46 + 47 + Ocasionalmente, el estilo de programación del kernel entrará en conflicto 48 + con el estilo obligatorio de un empleador. En tales casos, el estilo del 49 + kernel tendrá que prevalecer antes de que el código pueda ser fusionado. 50 + Incluir código en el kernel significa renunciar a cierto grado de control 51 + de varias maneras, incluida la forma en que se formatea el código. 52 + 53 + La otra trampa es asumir que el código que ya está en el kernel necesita 54 + urgentemente correcciones de estilo de programación. Los desarrolladores 55 + pueden comenzar a generar parches de reformateo como una forma de 56 + familiarizarse con el proceso o como una forma de incluir su nombre en los 57 + registros de cambios del kernel, o ambos. Pero las correcciones puramente 58 + de estilo de programación son vistas como ruido por la comunidad de 59 + desarrollo; tienden a recibir una recepción adversa. Por lo tanto, este 60 + tipo de parche es mejor evitarlo. Es natural corregir el estilo de una 61 + parte del código mientras se trabaja en él por otras razones, pero los 62 + cambios de estilo de programación no deben hacerse por sí mismos. 63 + 64 + El documento de estilo de programación tampoco debe leerse como una ley 65 + absoluta que nunca puede transgredirse. Si hay una buena razón para ir en 66 + contra del estilo (una línea que se vuelve mucho menos legible si se divide 67 + para ajustarse al límite de 80 columnas, por ejemplo), perfecto. 68 + 69 + Tenga en cuenta que también puedes usar la herramienta `clang-format` para 70 + ayudarle con estas reglas, para reformatear rápidamente partes de su código 71 + automáticamente y para revisar archivos completos a fin de detectar errores 72 + de estilo de programación, errores tipográficos y posibles mejoras. También 73 + es útil para ordenar `#includes`, alinear variables/macros, reformatear 74 + texto y otras tareas similares. Consulte el archivo 75 + `Documentation/dev-tools/clang-format.rst` para más detalles. 76 + 77 + Algunas configuraciones básicas del editor, como la indentación y los 78 + finales de línea, se configurarán automáticamente si utilizas un editor 79 + compatible con EditorConfig. Consulte el sitio web oficial de EditorConfig 80 + para obtener más información: https://editorconfig.org/ 81 + 82 + Capas de abstracción 83 + ******************** 84 + 85 + Los profesores de ciencias de la computación enseñan a los estudiantes a 86 + hacer un uso extensivo de capas de abstracción en nombre de la 87 + flexibilidad y el ocultamiento de la información. Sin duda, el kernel hace 88 + un uso extensivo de la abstracción; ningún proyecto que involucre varios 89 + millones de líneas de código podría sobrevivir de otra manera. Pero la 90 + experiencia ha demostrado que una abstracción excesiva o prematura puede 91 + ser tan perjudicial como la optimización prematura. La abstracción debe 92 + usarse en la medida necesaria y ya. 93 + 94 + A un nivel simple, considere una función que tiene un argumento que siempre 95 + se pasa como cero por todos los que la invocan. Uno podría mantener ese 96 + argumento por si alguien eventualmente necesita usar la flexibilidad 97 + adicional que proporciona. Sin embargo, para entonces, es probable que el 98 + código que implementa este argumento adicional se haya roto de alguna 99 + manera sutil que nunca se notó, porque nunca se ha utilizado. O, cuando 100 + surge la necesidad de flexibilidad adicional, no lo hace de una manera que 101 + coincida con la expectativa temprana del programador. Los desarrolladores 102 + del kernel rutinariamente enviarán parches para eliminar argumentos no 103 + utilizados; en general, no deberían añadirse en primer lugar. 104 + 105 + Las capas de abstracción que ocultan el acceso al hardware, a menudo para 106 + permitir que la mayor parte de un controlador se utilice con varios 107 + sistemas operativos, son especialmente mal vistas. Dichas capas oscurecen 108 + el código y pueden imponer una penalización en el rendimiento; no 109 + pertenecen al kernel de Linux. 110 + 111 + Por otro lado, si se encuentra copiando cantidades significativas de código 112 + de otro subsistema del kernel, es hora de preguntar si, de hecho, tendría 113 + sentido extraer parte de ese código en una biblioteca separada o 114 + implementar esa funcionalidad a un nivel superior. No tiene sentido 115 + replicar el mismo código en todo el kernel. 116 + 117 + Uso de #ifdef y del preprocesador en general 118 + ******************************************** 119 + 120 + El preprocesador de C tiene una tentación poderosa para algunos 121 + programadores de C, quienes lo ven como una forma de programar 122 + eficientemente una gran cantidad de flexibilidad en un archivo fuente. Pero 123 + el preprocesador no es C, y el uso intensivo de él da como resultado un 124 + código mucho más difícil de leer para otros y más difícil de verificar por 125 + el compilador para su corrección. El uso intensivo del preprocesador es 126 + asi siempre un signo de un código que necesita algo de limpieza. 127 + 128 + La compilación condicional con `#ifdef` es, de hecho, una característica 129 + poderosa, y se usa dentro del kernel. Pero hay poco deseo de ver código que 130 + sté salpicado liberalmente con bloques `#ifdef`. Como regla general, el uso 131 + de `#ifdef` debe limitarse a los archivos de encabezado siempre que sea 132 + posible. El código condicionalmente compilado puede confinarse a funciones 133 + que, si el código no va a estar presente, simplemente se convierten en 134 + vacías. El compilador luego optimizará silenciosamente la llamada a la 135 + función vacía. El resultado es un código mucho más limpio y fácil de 136 + seguir. 137 + 138 + Las macros del preprocesador de C presentan varios peligros, incluida la 139 + posible evaluación múltiple de expresiones con efectos secundarios y la 140 + falta de seguridad de tipos. Si te sientes tentado a definir una macro, 141 + considera crear una función en línea en su lugar. El código resultante será 142 + el mismo, pero las funciones en línea son más fáciles de leer, no evalúan 143 + sus argumentos varias veces y permiten que el compilador realice 144 + comprobaciones de tipo en los argumentos y el valor de retorno. 145 + 146 + Funciones en línea 147 + ****************** 148 + 149 + Las funciones en línea presentan su propio peligro, sin embargo. Los 150 + programadores pueden enamorarse de la eficiencia percibida al evitar una 151 + llamada a función y llenar un archivo fuente con funciones en línea. Esas 152 + funciones, sin embargo, pueden en realidad reducir el rendimiento. Dado que 153 + su código se replica en cada sitio de llamada, terminan hinchando el tamaño 154 + del kernel compilado. Eso, a su vez, crea presión en las cachés de memoria 155 + del procesador, lo que puede ralentizar la ejecución de manera drástica 156 + Las funciones en línea, como regla, deben ser bastante pequeñas y 157 + relativamente raras. El costo de una llamada a función, después de todo, no 158 + es tan alto; la creación de un gran número de funciones en línea es un 159 + ejemplo clásico de optimización prematura. 160 + 161 + En general, los programadores del kernel ignoran los efectos de caché bajo 162 + su propio riesgo. El clásico intercambio de tiempo/espacio que se enseña en 163 + las clases de estructuras de datos iniciales a menudo no se aplica al 164 + hardware contemporáneo. El espacio *es* tiempo, en el sentido de que un 165 + programa más grande se ejecutará más lentamente que uno más compacto. 166 + 167 + Los compiladores más recientes toman un papel cada vez más activo al 168 + decidir si una función dada debe realmente ser en línea o no. Por lo tanto, 169 + la colocación liberal de palabras clave "inline" puede no solo ser 170 + excesiva; también podría ser irrelevante. 171 + 172 + Bloqueo 173 + ******* 174 + 175 + En mayo de 2006, la pila de red "Devicescape" fue, con gran fanfarria, 176 + lanzada bajo la licencia GPL y puesta a disposición para su inclusión en el 177 + kernel principal. Esta donación fue una noticia bienvenida; el soporte para 178 + redes inalámbricas en Linux se consideraba, en el mejor de los casos, 179 + deficiente, y la pila de Devicescape ofrecía la promesa de solucionar esa 180 + situación. Sin embargo, este código no fue incluido en el kernel principal 181 + hasta junio de 2007 (versión 2.6.22). ¿Qué sucedió? 182 + 183 + Este código mostró varios signos de haber sido desarrollado a puertas 184 + cerradas en una empresa. Pero un problema importante en particular fue que 185 + no estaba diseñado para funcionar en sistemas multiprocesador. Antes de que 186 + esta pila de red (ahora llamada mac80211) pudiera fusionarse, se tuvo que 187 + implementar un esquema de bloqueo en ella. 188 + 189 + Hubo un tiempo en que se podía desarrollar código para el kernel de Linux 190 + sin pensar en los problemas de concurrencia que presentan los sistemas 191 + multiprocesador. Ahora, sin embargo, este documento se está escribiendo en 192 + una computadora portátil con dos núcleos. Incluso en sistemas de un solo 193 + procesador, el trabajo que se está realizando para mejorar la capacidad de 194 + respuesta aumentará el nivel de concurrencia dentro del kernel. Los días en 195 + que se podía escribir código para el kernel sin pensar en el bloqueo han 196 + quedado atrás. 197 + 198 + Cualquier recurso (estructuras de datos, registros de hardware, etc.) que 199 + pueda ser accedido concurrentemente por más de un hilo debe estar protegido 200 + por un bloqueo. El nuevo código debe escribirse teniendo en cuenta este 201 + requisito; implementar el bloqueo después de que el código ya ha sido 202 + desarrollado es una tarea mucho más difícil. Los desarrolladores del kernel 203 + deben tomarse el tiempo para comprender bien los primitivos de bloqueo 204 + disponibles para elegir la herramienta adecuada para el trabajo. El código 205 + que muestre una falta de atención a la concurrencia tendrá un camino 206 + difícil para ser incluido en el kernel principal. 207 + 208 + Regresiones 209 + *********** 210 + 211 + Un último peligro que vale la pena mencionar es el siguiente: puede ser 212 + tentador realizar un cambio (que puede traer grandes mejoras) que cause un 213 + problema para los usuarios existentes. Este tipo de cambio se llama una 214 + "regresión", y las regresiones se han vuelto muy mal recibidas en el kernel 215 + principal. Con pocas excepciones, los cambios que causan regresiones serán 216 + revertidos si la regresión no se puede solucionar de manera oportuna. Es 217 + mucho mejor evitar la regresión desde el principio. 218 + 219 + A menudo se argumenta que una regresión puede justificarse si hace que las 220 + cosas funcionen para más personas de las que crea problemas. ¿Por qué no 221 + hacer un cambio si trae nueva funcionalidad a diez sistemas por cada uno 222 + que rompe? La mejor respuesta a esta pregunta fue expresada por Linus en 223 + julio de 2007 (traducido): 224 + 225 + :: 226 + 227 + Entonces, no arreglamos errores introduciendo nuevos problemas. Eso 228 + lleva a la locura, y nadie sabe si realmente se avanza. ¿Es dos pasos 229 + adelante, uno atrás, o un paso adelante y dos atrás? 230 + 231 + (https://lwn.net/Articles/243460/). 232 + 233 + Un tipo de regresión especialmente mal recibido es cualquier tipo de cambio 234 + en la ABI del espacio de usuario. Una vez que se ha exportado una interfaz 235 + al espacio de usuario, debe ser soportada indefinidamente. Este hecho hace 236 + que la creación de interfaces para el espacio de usuario sea 237 + particularmente desafiante: dado que no pueden cambiarse de manera 238 + incompatible, deben hacerse bien desde el principio. Por esta razón, 239 + siempre se requiere una gran cantidad de reflexión, documentación clara y 240 + una amplia revisión para las interfaces del espacio de usuario. 241 + 242 + Herramientas de verificación de código 243 + ************************************** 244 + 245 + Por ahora, al menos, escribir código libre de errores sigue siendo un ideal 246 + que pocos de nosotros podemos alcanzar. Sin embargo, lo que podemos esperar 247 + hacer es detectar y corregir tantos de esos errores como sea posible antes 248 + de que nuestro código se integre en el kernel principal. Con ese fin, los 249 + desarrolladores del kernel han reunido una impresionante variedad de 250 + herramientas que pueden detectar una amplia variedad de problemas oscuros 251 + de manera automatizada. Cualquier problema detectado por el ordenador es 252 + un problema que no afectará a un usuario más adelante, por lo que es lógico 253 + que las herramientas automatizadas se utilicen siempre que sea posible. 254 + 255 + El primer paso es simplemente prestar atención a las advertencias 256 + producidas por el compilador. Las versiones contemporáneas de gcc pueden 257 + detectar (y advertir sobre) una gran cantidad de errores potenciales. Con 258 + bastante frecuencia, estas advertencias apuntan a problemas reales. El 259 + código enviado para revisión no debería, por regla general, producir 260 + ninguna advertencia del compilador. Al silenciar las advertencias, tenga 261 + cuidado de comprender la causa real e intente evitar "correcciones" que 262 + hagan desaparecer la advertencia sin abordar su causa. 263 + 264 + Tenga en cuenta que no todas las advertencias del compilador están 265 + habilitadas de forma predeterminada. Compile el kernel con 266 + "make KCFLAGS=-W" para obtener el conjunto completo. 267 + 268 + El kernel proporciona varias opciones de configuración que activan 269 + funciones de depuración; la mayoría de estas se encuentran en el submenú 270 + "kernel hacking". Varias de estas opciones deben estar activadas para 271 + cualquier kernel utilizado para desarrollo o pruebas. En particular, 272 + debería activar: 273 + 274 + - FRAME_WARN para obtener advertencias sobre marcos de pila más grandes 275 + que una cantidad determinada. La salida generada puede ser extensa, pero 276 + no es necesario preocuparse por las advertencias de otras partes del 277 + kernel. 278 + 279 + - DEBUG_OBJECTS agregará código para rastrear la vida útil de varios 280 + objetos creados por el kernel y advertir cuando se realicen cosas fuera 281 + de orden. Si está agregando un subsistema que crea (y exporta) objetos 282 + complejos propios, considere agregar soporte para la infraestructura de 283 + depuración de objetos. 284 + 285 + - DEBUG_SLAB puede encontrar una variedad de errores en la asignación y 286 + uso de memoria; debe usarse en la mayoría de los kernels de desarrollo. 287 + 288 + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP y DEBUG_MUTEXES encontrarán una serie 289 + de errores comunes de bloqueo. 290 + 291 + Hay bastantes otras opciones de depuración, algunas de las cuales se 292 + discutirán más adelante. Algunas de ellas tienen un impacto significativo 293 + en el rendimiento y no deben usarse todo el tiempo. Pero dedicar tiempo a 294 + aprender las opciones disponibles probablemente será recompensado muchas 295 + veces en poco tiempo. 296 + 297 + Una de las herramientas de depuración más pesadas es el verificador de 298 + bloqueos, o "lockdep". Esta herramienta rastreará la adquisición y 299 + liberación de cada bloqueo (spinlock o mutex) en el sistema, el orden en 300 + que se adquieren los bloqueos en relación entre sí, el entorno actual de 301 + interrupción, y más. Luego, puede asegurarse de que los bloqueos siempre se 302 + adquieran en el mismo orden, que las mismas suposiciones de interrupción se 303 + apliquen en todas las situaciones, y así sucesivamente. En otras palabras, 304 + lockdep puede encontrar varios escenarios en los que el sistema podría, en 305 + raras ocasiones, bloquearse. Este tipo de problema puede ser doloroso 306 + (tanto para desarrolladores como para usuarios) en un sistema desplegado; 307 + lockdep permite encontrarlos de manera automatizada con anticipación. El 308 + código con cualquier tipo de bloqueo no trivial debe ejecutarse con lockdep 309 + habilitado antes de ser enviado para su inclusión. 310 + 311 + Como programador diligente del kernel, sin duda alguna, verificará el 312 + estado de retorno de cualquier operación (como una asignación de memoria) 313 + que pueda fallar. Sin embargo, el hecho es que las rutas de recuperación de 314 + fallos resultantes probablemente no hayan sido probadas en absoluto. El 315 + código no probado tiende a ser código roto; podría tener mucha más 316 + confianza en su código si todas esas rutas de manejo de errores se hubieran 317 + ejercitado algunas veces. 318 + 319 + El kernel proporciona un marco de inyección de fallos que puede hacer 320 + precisamente eso, especialmente donde están involucradas las asignaciones 321 + de memoria. Con la inyección de fallos habilitada, un porcentaje 322 + configurable de las asignaciones de memoria fallarán; estas fallas pueden 323 + restringirse a un rango específico de código. Ejecutar con la inyección de 324 + fallos habilitada permite al programador ver cómo responde el código cuando 325 + las cosas van mal. Consulte 326 + Documentation/fault-injection/fault-injection.rst para obtener más 327 + información sobre cómo utilizar esta funcionalidad. 328 + 329 + Otros tipos de errores se pueden encontrar con la herramienta de análisis 330 + estático "sparse". Con sparse, el programador puede recibir advertencias 331 + sobre confusiones entre direcciones del espacio de usuario y del kernel, 332 + mezcla de cantidades big-endian y little-endian, el paso de valores enteros 333 + donde se espera un conjunto de banderas de bits, y así sucesivamente. 334 + Sparse debe instalarse por separado (puede encontrarse en 335 + https://sparse.wiki.kernel.org/index.php/Main_Page si su distribución no lo 336 + empaqueta); luego, puede ejecutarse en el código agregando "C=1" a su 337 + comando make. 338 + 339 + La herramienta "Coccinelle" (http://coccinelle.lip6.fr/) puede encontrar 340 + una amplia variedad de posibles problemas de codificación; también puede 341 + proponer correcciones para esos problemas. Bastantes "parches semánticos" 342 + para el kernel se han empaquetado en el directorio scripts/coccinelle; 343 + ejecutar "make coccicheck" ejecutará esos parches semánticos e informará 344 + sobre cualquier problema encontrado. Consulte: 345 + ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>` para 346 + obtener más información. 347 + 348 + Otros tipos de errores de portabilidad se encuentran mejor compilando su 349 + código para otras arquitecturas. Si no tiene un sistema S/390 o una placa 350 + de desarrollo Blackfin a mano, aún puede realizar el paso de compilación. 351 + Un gran conjunto de compiladores cruzados para sistemas x86 se puede 352 + encontrar en 353 + 354 + https://www.kernel.org/pub/tools/crosstool/ 355 + 356 + Muchos sistemas de compilación disponibles comercialmente también se pueden 357 + utilizar para compilar código de kernel para una amplia gama de 358 + arquitecturas. 359 + 360 + Los desarrolladores del kernel son afortunados: tienen acceso a una 361 + variedad de herramientas de verificación de código de la que los 362 + desarrolladores de la mayoría de los otros sistemas pueden estar celosos. 363 + Pero todas esas herramientas no servirán de nada si no las usa. El 364 + resultado final de ignorar estas herramientas es simple: alguien más puede 365 + notificarle de un problema en su código a través de un "oportuno" 366 + comentario en la lista de correo o, peor aún, el código problemático podría 367 + ser eliminado. Es mucho más fácil usar estas herramientas en primer lugar. 368 + 369 + Documentación 370 + ************* 371 + 372 + La documentación a menudo ha sido más la excepción que la regla en el 373 + desarrollo del kernel. Aun así, una documentación adecuada ayudará a 374 + facilitar la integración de nuevo código en el kernel, hará la vida más 375 + fácil a otros desarrolladores, y será útil para sus usuarios. En muchos 376 + casos, la inclusión de documentación se ha vuelto esencialmente 377 + obligatoria. 378 + 379 + La primera pieza de documentación para cualquier parche es su changelog 380 + asociado. Las entradas de registro deben describir el problema que se está 381 + esolviendo, la forma de la solución, las personas que trabajaron en el 382 + parche, cualquier efecto relevante en el rendimiento, y cualquier otra cosa 383 + que pueda ser necesaria para entender el parche. Asegúrese de que el 384 + changelog diga *por qué* el parche vale la pena ser aplicado; un 385 + sorprendente número de desarrolladores no proporciona esa información. 386 + 387 + Cualquier código que agregue una nueva interfaz para el espacio de usuario, 388 + incluidos los nuevos archivos de sysfs o /proc, debe incluir documentación 389 + de esa interfaz que permita a los desarrolladores del espacio de usuario 390 + saber con qué están trabajando. Consulte `Documentation/ABI/README` para 391 + una descripción de cómo debe formatearse esta documentación y qué 392 + información debe proporcionarse. 393 + 394 + El archivo 395 + :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>` 396 + describe todos los parámetros de arranque del kernel. Cualquier parche que 397 + agregue nuevos parámetros debe agregar las entradas correspondientes a este 398 + archivo. 399 + 400 + Cualquier nueva opción de configuración debe ir acompañada de un texto de 401 + ayuda que explique claramente las opciones y cuándo el usuario podría 402 + querer seleccionarlas. 403 + 404 + La información de la API interna para muchos subsistemas está documentada 405 + mediante comentarios especialmente formateados; estos comentarios pueden 406 + extraerse y formatearse de diversas maneras mediante el script 407 + "kernel-doc". Si está trabajando dentro de un subsistema que tiene 408 + comentarios de kerneldoc, debe mantenerlos y agregarlos según corresponda 409 + para las funciones disponibles externamente. Incluso en áreas que no han 410 + sido tan documentadas, no hay ningún inconveniente en agregar comentarios 411 + de kerneldoc para el futuro; de hecho, esta puede ser una actividad útil 412 + para desarrolladores de kernel principiantes. El formato de estos 413 + comentarios, junto con alguna información sobre cómo crear plantillas de 414 + kerneldoc, se puede encontrar en 415 + :ref:`Documentation/doc-guide/ <doc_guide>`. 416 + 417 + Cualquiera que lea una cantidad significativa de código existente del 418 + kernel notará que, a menudo, los comentarios son notables por su ausencia. 419 + Una vez más, las expectativas para el nuevo código son más altas que en el 420 + pasado; integrar código sin comentarios será más difícil. Dicho esto, hay 421 + poco deseo de tener código excesivamente comentado. El código en sí debe 422 + ser legible, con comentarios que expliquen los aspectos más sutiles. 423 + 424 + Ciertas cosas siempre deben comentarse. El uso de barreras de memoria debe 425 + ir acompañado de una línea que explique por qué la barrera es necesaria. 426 + Las reglas de bloqueo para las estructuras de datos generalmente necesitan 427 + explicarse en algún lugar. Las estructuras de datos importantes en general 428 + necesitan documentación completa. Las dependencias no obvias entre 429 + fragmentos de código separados deben señalarse. Cualquier cosa que pueda 430 + tentar a un maintainer de código a hacer una "limpieza" incorrecta necesita 431 + un comentario que explique por qué se hace de esa manera. Y así 432 + sucesivamente. 433 + 434 + Cambios en la API interna 435 + ************************* 436 + 437 + La interfaz binaria proporcionada por el kernel al espacio de usuario no se 438 + puede romper, excepto en las circunstancias más graves. Las interfaces de 439 + programación internas del kernel, en cambio, son altamente fluidas y pueden 440 + cambiarse cuando surge la necesidad. Si usted se encuentra teniendo que 441 + hacer un rodeo alrededor de una API del kernel, o simplemente no utilizando 442 + una funcionalidad específica porque no cumple con sus necesidades, eso 443 + puede ser una señal de que la API necesita cambiar. Como desarrollador del 444 + kernel, usted está autorizado a hacer esos cambios. 445 + 446 + Hay, por supuesto, algunas condiciones. Los cambios en la API se pueden 447 + hacer, pero necesitan estar bien justificados. Entonces, cualquier parche 448 + que realice un cambio en la API interna debe ir acompañado de una 449 + descripción de cuál es el cambio y por qué es necesario. Este tipo de 450 + cambio también debe desglosarse en un parche separado, en lugar de estar 451 + enterrado dentro de un parche más grande. 452 + 453 + La otra condición es que un desarrollador que cambia una API interna 454 + generalmente está encargado de la tarea de corregir cualquier código dentro 455 + del árbol del kernel que se vea afectado por el cambio. Para una función 456 + ampliamente utilizada, este deber puede llevar a literalmente cientos o 457 + miles de cambios, muchos de los cuales probablemente entren en conflicto 458 + con el trabajo que otros desarrolladores están realizando. No hace falta 459 + decir que esto puede ser un trabajo grande, por lo que es mejor asegurarse 460 + de que la justificación sea sólida. Tenga en cuenta que la herramienta 461 + Coccinelle puede ayudar con los cambios de API a gran escala. 462 + 463 + Cuando se realice un cambio incompatible en la API, siempre que sea 464 + posible, se debe asegurar que el código que no ha sido actualizado sea 465 + detectado por el compilador. Esto le ayudará a estar seguro de que ha 466 + encontrado todos los usos en el árbol de esa interfaz. También alertará a 467 + los desarrolladores de código fuera del árbol de que hay un cambio al que 468 + necesitan responder. Apoyar el código fuera del árbol no es algo de lo que 469 + los desarrolladores del kernel deban preocuparse, pero tampoco tenemos que 470 + dificultarles la vida más de lo necesario.
+1
Documentation/translations/sp_SP/process/development-process.rst
··· 26 26 1.Intro 27 27 2.Process 28 28 3.Early-stage 29 + 4.Coding