[
{
"path": "LICENSE",
"content": "Copyright (c) 2023 Artem Zakirullin (https://github.com/zakirullin)\n\nAttribution 4.0 International\n\n=======================================================================\n\nCreative Commons Corporation (\"Creative Commons\") is not a law firm and\ndoes not provide legal services or legal advice. Distribution of\nCreative Commons public licenses does not create a lawyer-client or\nother relationship. Creative Commons makes its licenses and related\ninformation available on an \"as-is\" basis. Creative Commons gives no\nwarranties regarding its licenses, any material licensed under their\nterms and conditions, or any related information. Creative Commons\ndisclaims all liability for damages resulting from their use to the\nfullest extent possible.\n\nUsing Creative Commons Public Licenses\n\nCreative Commons public licenses provide a standard set of terms and\nconditions that creators and other rights holders may use to share\noriginal works of authorship and other material subject to copyright\nand certain other rights specified in the public license below. The\nfollowing considerations are for informational purposes only, are not\nexhaustive, and do not form part of our licenses.\n\n Considerations for licensors: Our public licenses are\n intended for use by those authorized to give the public\n permission to use material in ways otherwise restricted by\n copyright and certain other rights. Our licenses are\n irrevocable. Licensors should read and understand the terms\n and conditions of the license they choose before applying it.\n Licensors should also secure all rights necessary before\n applying our licenses so that the public can reuse the\n material as expected. Licensors should clearly mark any\n material not subject to the license. This includes other CC-\n licensed material, or material used under an exception or\n limitation to copyright. More considerations for licensors:\n\twiki.creativecommons.org/Considerations_for_licensors\n\n Considerations for the public: By using one of our public\n licenses, a licensor grants the public permission to use the\n licensed material under specified terms and conditions. If\n the licensor's permission is not necessary for any reason--for\n example, because of any applicable exception or limitation to\n copyright--then that use is not regulated by the license. Our\n licenses grant only permissions under copyright and certain\n other rights that a licensor has authority to grant. Use of\n the licensed material may still be restricted for other\n reasons, including because others have copyright or other\n rights in the material. A licensor may make special requests,\n such as asking that all changes be marked or described.\n Although not required by our licenses, you are encouraged to\n respect those requests where reasonable. More_considerations\n for the public:\n\twiki.creativecommons.org/Considerations_for_licensees\n\n=======================================================================\n\nCreative Commons Attribution 4.0 International Public License\n\nBy exercising the Licensed Rights (defined below), You accept and agree\nto be bound by the terms and conditions of this Creative Commons\nAttribution 4.0 International Public License (\"Public License\"). To the\nextent this Public License may be interpreted as a contract, You are\ngranted the Licensed Rights in consideration of Your acceptance of\nthese terms and conditions, and the Licensor grants You such rights in\nconsideration of benefits the Licensor receives from making the\nLicensed Material available under these terms and conditions.\n\n\nSection 1 -- Definitions.\n\n a. Adapted Material means material subject to Copyright and Similar\n Rights that is derived from or based upon the Licensed Material\n and in which the Licensed Material is translated, altered,\n arranged, transformed, or otherwise modified in a manner requiring\n permission under the Copyright and Similar Rights held by the\n Licensor. For purposes of this Public License, where the Licensed\n Material is a musical work, performance, or sound recording,\n Adapted Material is always produced where the Licensed Material is\n synched in timed relation with a moving image.\n\n b. Adapter's License means the license You apply to Your Copyright\n and Similar Rights in Your contributions to Adapted Material in\n accordance with the terms and conditions of this Public License.\n\n c. Copyright and Similar Rights means copyright and/or similar rights\n closely related to copyright including, without limitation,\n performance, broadcast, sound recording, and Sui Generis Database\n Rights, without regard to how the rights are labeled or\n categorized. For purposes of this Public License, the rights\n specified in Section 2(b)(1)-(2) are not Copyright and Similar\n Rights.\n\n d. Effective Technological Measures means those measures that, in the\n absence of proper authority, may not be circumvented under laws\n fulfilling obligations under Article 11 of the WIPO Copyright\n Treaty adopted on December 20, 1996, and/or similar international\n agreements.\n\n e. Exceptions and Limitations means fair use, fair dealing, and/or\n any other exception or limitation to Copyright and Similar Rights\n that applies to Your use of the Licensed Material.\n\n f. Licensed Material means the artistic or literary work, database,\n or other material to which the Licensor applied this Public\n License.\n\n g. Licensed Rights means the rights granted to You subject to the\n terms and conditions of this Public License, which are limited to\n all Copyright and Similar Rights that apply to Your use of the\n Licensed Material and that the Licensor has authority to license.\n\n h. Licensor means the individual(s) or entity(ies) granting rights\n under this Public License.\n\n i. Share means to provide material to the public by any means or\n process that requires permission under the Licensed Rights, such\n as reproduction, public display, public performance, distribution,\n dissemination, communication, or importation, and to make material\n available to the public including in ways that members of the\n public may access the material from a place and at a time\n individually chosen by them.\n\n j. Sui Generis Database Rights means rights other than copyright\n resulting from Directive 96/9/EC of the European Parliament and of\n the Council of 11 March 1996 on the legal protection of databases,\n as amended and/or succeeded, as well as other essentially\n equivalent rights anywhere in the world.\n\n k. You means the individual or entity exercising the Licensed Rights\n under this Public License. Your has a corresponding meaning.\n\n\nSection 2 -- Scope.\n\n a. License grant.\n\n 1. Subject to the terms and conditions of this Public License,\n the Licensor hereby grants You a worldwide, royalty-free,\n non-sublicensable, non-exclusive, irrevocable license to\n exercise the Licensed Rights in the Licensed Material to:\n\n a. reproduce and Share the Licensed Material, in whole or\n in part; and\n\n b. produce, reproduce, and Share Adapted Material.\n\n 2. Exceptions and Limitations. For the avoidance of doubt, where\n Exceptions and Limitations apply to Your use, this Public\n License does not apply, and You do not need to comply with\n its terms and conditions.\n\n 3. Term. The term of this Public License is specified in Section\n 6(a).\n\n 4. Media and formats; technical modifications allowed. The\n Licensor authorizes You to exercise the Licensed Rights in\n all media and formats whether now known or hereafter created,\n and to make technical modifications necessary to do so. The\n Licensor waives and/or agrees not to assert any right or\n authority to forbid You from making technical modifications\n necessary to exercise the Licensed Rights, including\n technical modifications necessary to circumvent Effective\n Technological Measures. For purposes of this Public License,\n simply making modifications authorized by this Section 2(a)\n (4) never produces Adapted Material.\n\n 5. Downstream recipients.\n\n a. Offer from the Licensor -- Licensed Material. Every\n recipient of the Licensed Material automatically\n receives an offer from the Licensor to exercise the\n Licensed Rights under the terms and conditions of this\n Public License.\n\n b. No downstream restrictions. You may not offer or impose\n any additional or different terms or conditions on, or\n apply any Effective Technological Measures to, the\n Licensed Material if doing so restricts exercise of the\n Licensed Rights by any recipient of the Licensed\n Material.\n\n 6. No endorsement. Nothing in this Public License constitutes or\n may be construed as permission to assert or imply that You\n are, or that Your use of the Licensed Material is, connected\n with, or sponsored, endorsed, or granted official status by,\n the Licensor or others designated to receive attribution as\n provided in Section 3(a)(1)(A)(i).\n\n b. Other rights.\n\n 1. Moral rights, such as the right of integrity, are not\n licensed under this Public License, nor are publicity,\n privacy, and/or other similar personality rights; however, to\n the extent possible, the Licensor waives and/or agrees not to\n assert any such rights held by the Licensor to the limited\n extent necessary to allow You to exercise the Licensed\n Rights, but not otherwise.\n\n 2. Patent and trademark rights are not licensed under this\n Public License.\n\n 3. To the extent possible, the Licensor waives any right to\n collect royalties from You for the exercise of the Licensed\n Rights, whether directly or through a collecting society\n under any voluntary or waivable statutory or compulsory\n licensing scheme. In all other cases the Licensor expressly\n reserves any right to collect such royalties.\n\n\nSection 3 -- License Conditions.\n\nYour exercise of the Licensed Rights is expressly made subject to the\nfollowing conditions.\n\n a. Attribution.\n\n 1. If You Share the Licensed Material (including in modified\n form), You must:\n\n a. retain the following if it is supplied by the Licensor\n with the Licensed Material:\n\n i. identification of the creator(s) of the Licensed\n Material and any others designated to receive\n attribution, in any reasonable manner requested by\n the Licensor (including by pseudonym if\n designated);\n\n ii. a copyright notice;\n\n iii. a notice that refers to this Public License;\n\n iv. a notice that refers to the disclaimer of\n warranties;\n\n v. a URI or hyperlink to the Licensed Material to the\n extent reasonably practicable;\n\n b. indicate if You modified the Licensed Material and\n retain an indication of any previous modifications; and\n\n c. indicate the Licensed Material is licensed under this\n Public License, and include the text of, or the URI or\n hyperlink to, this Public License.\n\n 2. You may satisfy the conditions in Section 3(a)(1) in any\n reasonable manner based on the medium, means, and context in\n which You Share the Licensed Material. For example, it may be\n reasonable to satisfy the conditions by providing a URI or\n hyperlink to a resource that includes the required\n information.\n\n 3. If requested by the Licensor, You must remove any of the\n information required by Section 3(a)(1)(A) to the extent\n reasonably practicable.\n\n 4. If You Share Adapted Material You produce, the Adapter's\n License You apply must not prevent recipients of the Adapted\n Material from complying with this Public License.\n\n\nSection 4 -- Sui Generis Database Rights.\n\nWhere the Licensed Rights include Sui Generis Database Rights that\napply to Your use of the Licensed Material:\n\n a. for the avoidance of doubt, Section 2(a)(1) grants You the right\n to extract, reuse, reproduce, and Share all or a substantial\n portion of the contents of the database;\n\n b. if You include all or a substantial portion of the database\n contents in a database in which You have Sui Generis Database\n Rights, then the database in which You have Sui Generis Database\n Rights (but not its individual contents) is Adapted Material; and\n\n c. You must comply with the conditions in Section 3(a) if You Share\n all or a substantial portion of the contents of the database.\n\nFor the avoidance of doubt, this Section 4 supplements and does not\nreplace Your obligations under this Public License where the Licensed\nRights include other Copyright and Similar Rights.\n\n\nSection 5 -- Disclaimer of Warranties and Limitation of Liability.\n\n a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE\n EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS\n AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF\n ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,\n IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,\n WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR\n PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,\n ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT\n KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT\n ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.\n\n b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE\n TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,\n NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,\n INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,\n COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR\n USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN\n ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR\n DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR\n IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.\n\n c. The disclaimer of warranties and limitation of liability provided\n above shall be interpreted in a manner that, to the extent\n possible, most closely approximates an absolute disclaimer and\n waiver of all liability.\n\n\nSection 6 -- Term and Termination.\n\n a. This Public License applies for the term of the Copyright and\n Similar Rights licensed here. However, if You fail to comply with\n this Public License, then Your rights under this Public License\n terminate automatically.\n\n b. Where Your right to use the Licensed Material has terminated under\n Section 6(a), it reinstates:\n\n 1. automatically as of the date the violation is cured, provided\n it is cured within 30 days of Your discovery of the\n violation; or\n\n 2. upon express reinstatement by the Licensor.\n\n For the avoidance of doubt, this Section 6(b) does not affect any\n right the Licensor may have to seek remedies for Your violations\n of this Public License.\n\n c. For the avoidance of doubt, the Licensor may also offer the\n Licensed Material under separate terms or conditions or stop\n distributing the Licensed Material at any time; however, doing so\n will not terminate this Public License.\n\n d. Sections 1, 5, 6, 7, and 8 survive termination of this Public\n License.\n\n\nSection 7 -- Other Terms and Conditions.\n\n a. The Licensor shall not be bound by any additional or different\n terms or conditions communicated by You unless expressly agreed.\n\n b. Any arrangements, understandings, or agreements regarding the\n Licensed Material not stated herein are separate from and\n independent of the terms and conditions of this Public License.\n\n\nSection 8 -- Interpretation.\n\n a. For the avoidance of doubt, this Public License does not, and\n shall not be interpreted to, reduce, limit, restrict, or impose\n conditions on any use of the Licensed Material that could lawfully\n be made without permission under this Public License.\n\n b. To the extent possible, if any provision of this Public License is\n deemed unenforceable, it shall be automatically reformed to the\n minimum extent necessary to make it enforceable. If the provision\n cannot be reformed, it shall be severed from this Public License\n without affecting the enforceability of the remaining terms and\n conditions.\n\n c. No term or condition of this Public License will be waived and no\n failure to comply consented to unless expressly agreed to by the\n Licensor.\n\n d. Nothing in this Public License constitutes or may be interpreted\n as a limitation upon, or waiver of, any privileges and immunities\n that apply to the Licensor or You, including from the legal\n processes of any jurisdiction or authority.\n\n\n=======================================================================\n\nCreative Commons is not a party to its public\nlicenses. Notwithstanding, Creative Commons may elect to apply one of\nits public licenses to material it publishes and in those instances\nwill be considered the “Licensor.” The text of the Creative Commons\npublic licenses is dedicated to the public domain under the CC0 Public\nDomain Dedication. Except for the limited purpose of indicating that\nmaterial is shared under a Creative Commons public license or as\notherwise permitted by the Creative Commons policies published at\ncreativecommons.org/policies, Creative Commons does not authorize the\nuse of the trademark \"Creative Commons\" or any other trademark or logo\nof Creative Commons without its prior written consent including,\nwithout limitation, in connection with any unauthorized modifications\nto any of its public licenses or any other arrangements,\nunderstandings, or agreements concerning use of licensed material. For\nthe avoidance of doubt, this paragraph does not form part of the\npublic licenses.\n\nCreative Commons may be contacted at creativecommons.org."
},
{
"path": "README.es.md",
"content": "# La carga cognitiva es lo que importa\n\n[Prompt](https://github.com/zakirullin/cognitive-load/blob/main/README.prompt.md) | [Blog version](https://minds.md/zakirullin/cognitive) | [Chinese](https://github.com/zakirullin/cognitive-load/blob/main/README.zh-cn.md) | [Korean](README.ko.md) | [Turkish](README.tr.md) | [Japanese](README.ja.md) | [Spanish](README.es.md)\n\n*Este es un documento \"vivo\", última actualización: octubre de 2025. ¡Tus contribuciones son bienvenidas!*\n\n## Introducción\nExisten muchas palabras de moda y “mejores prácticas” por ahí, pero la mayoría han fracasado. Fracasaron porque fueron imaginadas, no reales. Estas ideas se basaban en la estética y en juicios subjetivos. Necesitamos algo más fundamental, algo que no pueda estar equivocado.\n\nA veces sentimos confusión al leer el código. La confusión cuesta tiempo y dinero. La confusión es causada por una alta *carga cognitiva*. No es un concepto elegante y abstracto, sino **una limitación humana fundamental**. No es imaginaria, está ahí y podemos sentirla. \n\nComo pasamos mucho más tiempo leyendo y entendiendo código que escribiéndolo, deberíamos preguntarnos constantemente si estamos incorporando una carga cognitiva excesiva en nuestro código.\n\n## Carga cognitiva\n> La carga cognitiva es cuánto necesita pensar un desarrollador para completar una tarea.\n\nAl leer código, incorporas en tu mente cosas como los valores de las variables, la lógica del flujo de control y las secuencias de llamadas. La persona promedio puede mantener aproximadamente [cuatro de estos fragmentos](https://github.com/zakirullin/cognitive-load/issues/16) en la memoria de trabajo. Una vez que la carga cognitiva alcanza este umbral, se vuelve mucho más difícil entender las cosas.\n\n*Supongamos que se nos ha pedido hacer algunas correcciones en un proyecto completamente desconocido. Nos dijeron que un desarrollador muy inteligente había contribuido en él. Se usaron muchas arquitecturas geniales, bibliotecas elegantes y tecnologías de moda. En otras palabras, **el autor había creado una alta carga cognitiva para nosotros.***\n\n\n
![\"Cognitive](\"/img/cognitiveloadv6.png\")
\n
\n Carga cognitiva e interrupciones
\n \n
![](\"img/interruption.jpeg\")
\n
\n\n> Vamos a utilizar \"carga cognitiva\" en un sentido informal; a veces se alineará con el concepto científico específico de Carga Cognitiva, pero no sabemos lo suficiente sobre dónde coincide y dónde no.\n\n## Tipos de carga cognitiva\n**Intrínseca**: causada por la dificultad inherente de una tarea. No se puede reducir; es la esencia misma del desarrollo de software.\n\n**Extraña**: generada por la forma en que se presenta la información. Causada por factores que no son directamente relevantes para la tarea, como las peculiaridades del autor. Se pueden reducir considerablemente. Nos centraremos en este tipo de carga cognitiva.\n\n\n
![\"Intrínsica](\"/img/smartauthorv14thanksmari.png\")
\n
\n
![\"Módulo](\"/img/deepmodulev8.png\")
\n
\n Las cosas importantes deben ser grandes, ejemplos
\n
\n \n
![\"Limpio](\"/img/dirty.png\")
\n
Si permites que tus funciones \"cruciales\" importantes sean más grandes (\"sucias\") es más fácil distinguirlas del mar de funciones, son obviamente importantes: ¡solo míralas, son grandes!
\n Esta imagen está tomada del artículo Codin' Dirty de Carson Gross. Allí encontrarás ejemplos del mundo real de funciones profundas.\n \n\nP.D. Si crees que apoyamos objetos divinos inflados y con demasiadas responsabilidades, te equivocas.\n\n## Responsable de una cosa\nCon demasiada frecuencia, terminamos creando muchos módulos superficiales, siguiendo el principio impreciso de que «un módulo debe ser responsable de una sola cosa». ¿Qué es esta cosa difusa? Instanciar un objeto es una cosa, ¿verdad? Entonces, [MetricsProviderFactoryFactory](https://minds.md/benji/frameworks) parece estar bien. **Los nombres e interfaces de dichas clases tienden a ser más exigentes mentalmente que sus implementaciones completas, ¿qué tipo de abstracción es esa?** Algo salió mal. \n\nRealizamos cambios en nuestros sistemas para satisfacer a nuestros usuarios y actores. Somos responsables ante ellos.\n\n> Un módulo debe ser responsable ante un solo usuario o actor.\n\nDe esto se trata el Principio de Responsabilidad Única. En pocas palabras, si introducimos un error en un lugar y luego dos profesionales distintos vienen a quejarse, hemos violado el principio. No tiene nada que ver con la cantidad de tareas que realizamos en nuestro módulo. \n\nPero incluso ahora, esta regla puede ser más perjudicial que beneficiosa. Este principio puede entenderse de tantas maneras diferentes como individuos. Un mejor enfoque sería analizar la carga cognitiva que genera. Es mentalmente exigente recordar que un cambio en un lugar puede desencadenar una cadena de reacciones en diferentes áreas del negocio. Y eso es todo, sin términos complejos que aprender. \n\n## Demasiados microservicios superficiales\nEste principio de módulo superficial-profundo es independiente de la escala y puede aplicarse a la arquitectura de microservicios. Demasiados microservicios superficiales no servirán de nada: la industria se encamina hacia \"macroservicios\", es decir, servicios que no son tan superficiales (=profundos). Uno de los fenómenos más graves y difíciles de solucionar es el llamado monolito distribuido, que a menudo resulta de esta separación superficial excesivamente granular.\n\nEn una ocasión, asesoré a una startup donde un equipo de cinco desarrolladores introdujo 17(!) microservicios. Llevaban 10 meses de retraso y estaban lejos de su lanzamiento público. Cada nuevo requisito implicaba cambios en 4+ microservicios. Reproducir y depurar un problema en un sistema tan distribuido requería muchísimo tiempo. Tanto el tiempo de comercialización como la carga cognitiva eran inaceptablemente altos. `🤯`\n\n¿Es esta la manera correcta de abordar la incertidumbre de un nuevo sistema? Es extremadamente difícil establecer los límites lógicos correctos al principio. La clave está en tomar decisiones lo más tarde posible, ya que es cuando se dispone de más información. Al introducir una capa de red desde el comienzo, dificultamos la reversión de nuestras decisiones de diseño desde el principio. La única justificación del equipo fue: «Las empresas FAANG demostraron la eficacia de la arquitectura de microservicios». *Hola, tienen que dejar de soñar a lo grande.*\n\nEl [debate Tanenbaum-Torvalds](https://en.wikipedia.org/wiki/Tanenbaum%E2%80%93Torvalds_debate) argumentó que el diseño monolítico de Linux era defectuoso y obsoleto, y que debería utilizarse una arquitectura de micronúcleo. De hecho, el diseño de micronúcleo parecía ser superior tanto desde un punto de vista teórico como estético. En la práctica, tres décadas después, GNU Hurd, basado en micronúcleo, sigue en desarrollo, y Linux monolítico está en todas partes. Esta página funciona con Linux, tu tetera inteligente funciona con Linux. Con Linux monolítico.\n\nUn monolito bien diseñado con módulos verdaderamente aislados suele ser mucho más flexible que un conjunto de microservicios. Además, requiere mucho menos esfuerzo cognitivo para su mantenimiento. Solo cuando la necesidad de implementaciones independientes se vuelve crucial, como al escalar el equipo de desarrollo, se debe considerar añadir una capa de red entre los módulos, los futuros microservicios.\n\n## Lenguajes ricos en funciones\nNos emocionamos cuando se lanzan nuevas funciones en nuestro lenguaje favorito. Dedicamos tiempo a aprenderlas y desarrollamos código a partir de ellas.\n\nSi hay muchas funciones, podemos pasar media hora probando algunas líneas de código para usar una u otra. Y es una pérdida de tiempo. Y lo que es peor, **cuando vuelvas más tarde, ¡tendrás que replantearte ese proceso!**\n \n**No sólo tienes que entender este complicado programa, tienes que entender por qué un programador decidió que esta era la forma de abordar un problema a partir de las características disponibles.** `🤯`\n\nEstas declaraciones las hace nada menos que Rob Pike.\n\n> Reduce la carga cognitiva limitando el número de opciones. \n\nLas características del lenguaje están bien, siempre que sean ortogonales entre sí.\n\n\n Reflexiones de un ingeniero con 20 años de experiencia en C++ ⭐️
\n
\n El otro día estaba mirando mi lector RSS y me di cuenta de que tengo unos trescientos artículos sin leer bajo la etiqueta \"C++\". No he leído ni un solo artículo sobre el lenguaje desde el verano pasado, ¡y me siento genial!
\n Llevo 20 años usando C++, casi dos tercios de mi vida. Gran parte de mi experiencia reside en lidiar con los aspectos más oscuros del lenguaje (como comportamientos indefinidos de todo tipo). No es una experiencia reutilizable, y resulta un poco inquietante tirarlo todo ahora.
\n Como podrás imaginar, el token || tiene un significado diferente en requires ((!P<T> || !Q<T>)) y en requires (!(P<T> || Q<T>)). El primero es la disyunción de restricción, el segundo es el viejo operador lógico OR, y se comportan de manera diferente.
\n No se puede asignar espacio para un tipo trivial y simplemente memcpy un conjunto de bytes sin esfuerzo adicional; eso no iniciará el ciclo de vida de un objeto. Esto ocurría antes de C++20. Se corrigió en C++20, pero la carga cognitiva del lenguaje solo ha aumentado.
\n La carga cognitiva crece constantemente, incluso después de que se hayan corregido algunas cosas. Debería saber qué se corrigió, cuándo se corrigió y cómo era antes. Después de todo, soy un profesional. Claro, C++ es bueno en la compatibilidad con versiones anteriores, lo que también significa que te enfrentarás a ellas. Por ejemplo, el mes pasado un colega me preguntó sobre cierto comportamiento en C++03.🤯
\n Había 20 métodos de inicialización. Se había añadido una sintaxis de inicialización uniforme. Ahora tenemos 21 métodos de inicialización. Por cierto, ¿alguien recuerda las reglas para seleccionar constructores de la lista de inicializadores? Algo sobre la conversión implícita con la mínima pérdida de información, pero si el valor se conoce estáticamente, entonces...🤯
\n Este aumento de la carga cognitiva no se debe a una tarea empresarial en cuestión. No es una complejidad intrínseca del dominio. Simplemente existe debido a razones históricas (carga cognitiva extraña).
\n Tuve que idear algunas reglas. Por ejemplo, si esa línea de código no es tan obvia y tengo que recordar el estándar, mejor no escribirla así. El estándar tiene unas 1500 páginas, por cierto.
\n De ninguna manera estoy tratando de culpar a C++. Me encanta el lenguaje. Es solo que ahora estoy cansado.
\n Gracias a 0xd34df00d por el escrito.
\n \n\n\n## Lógica de negocio y códigos de estado HTTP\nEn el backend, devolvemos: \n`401` para token JWT vencido\n`403` para acceso insuficiente\n`418` para usuarios bloqueados \n\nLos ingenieros del frontend usan la API del backend para implementar la funcionalidad de inicio de sesión. Tienen que crear temporalmente la siguiente carga cognitiva en sus cerebros:\n`401` es para token JWT vencido // `🧠+`, ok solo recuérdalo temporalmente \n`403` es para acceso insuficeinte // `🧠++` \n`418` es para usuarios bloqueados // `🧠+++` \n\nLos desarrolladores frontend introducirían (con suerte) algún tipo de diccionario «estado numérico -> significado» de su lado, de modo que las generaciones posteriores de colaboradores no tuvieran que recrear este mapeo en sus cerebros.\n\nEntonces entran en juego los ingenieros de control de calidad:\n\"Oye, tengo el estado `403`, ¿ese token está vencido o no hay suficiente acceso?\"\n**Los ingenieros de control de calidad no pueden comenzar directamente con las pruebas, porque primero tienen que recrear la carga cognitiva que alguna vez crearon los ingenieros del backend.**\n\n¿Por qué mantener esta asignación personalizada en nuestra memoria de trabajo? Es mejor abstraer los detalles de su negocio del protocolo de transferencia HTTP y devolver códigos autodescriptivos directamente en el cuerpo de la respuesta:\n```json\n{\n \"code\": \"jwt_ha_expirado\"\n}\n```\n\nCarga cognitiva en el frontend: `🧠` (genial, no se tienen en cuenta los hechos)\nCarga cognitiva en el control de calidad: `🧠`\n\nLa misma regla se aplica a todo tipo de estados numéricos (en la base de datos o donde sea): **usa cadenas autodescriptivas.** No estamos en la era de las computadoras de 640K para optimizar la memoria.\n\n> La gente pasa tiempo discutiendo entre el `401` y el `403`, tomando decisiones basadas en sus propios modelos mentales. Se incorporan nuevos desarrolladores y necesitan recrear ese proceso de pensamiento. Puede que hayas documentado los \"porqués\" (ADR) de tu código, ayudando a los recién llegados a comprender las decisiones tomadas. Pero al final, simplemente no tiene sentido. Podemos separar los errores en relacionados con el usuario o con el servidor, pero aparte de eso, la información es bastante confusa.\n\nP.D.: A menudo resulta difícil distinguir entre \"autenticación\" y \"autorización\". Podemos usar términos más simples como [\"inicio de sesión\" y \"permisos\"](https://ntietz.com/blog/lets-say-instead-of-auth/) para reducir la carga cognitiva.\n\n## Abusar del principio DRY\n\nNo repetirse es uno de los primeros principios que se enseñan como ingenieros de software. Está tan arraigado en nosotros que no soportamos unas pocas líneas de código adicionales. Aunque en general es una regla buena y fundamental, su uso excesivo genera una carga cognitiva que no podemos manejar.\n\nHoy en día, todos desarrollamos software basado en componentes lógicamente separados. A menudo, estos se distribuyen entre múltiples bases de código que representan servicios separados. Al esforzarnos por eliminar cualquier repetición, podemos terminar creando un acoplamiento estrecho entre componentes no relacionados. Como resultado, los cambios en una parte pueden tener consecuencias imprevistas en otras áreas aparentemente no relacionadas. También pueden dificultar la capacidad de reemplazar o modificar componentes individuales sin afectar a todo el sistema.`🤯` \n\nDe hecho, el mismo problema surge incluso dentro de un mismo módulo. Podrías extraer alguna funcionalidad común demasiado pronto, basándote en similitudes percibidas que podrían no existir a largo plazo. Esto puede generar abstracciones innecesarias difíciles de modificar o ampliar.\n\nRob Pike una vez dijo:\n\n> Un poco de copia es mejor que un poco de dependencia.\n\nNos sentimos tentados a no reinventar la rueda con tanta fuerza que estamos dispuestos a importar bibliotecas grandes y pesadas para usar una función pequeña que podríamos escribir fácilmente nosotros mismos.\n\n**Todas tus dependencias son tu código.** Recorrer más de 10 niveles de seguimiento de pila de alguna biblioteca importada y descubrir qué salió mal (*porque las cosas salen mal*) es doloroso.\n\n## Acoplamiento estrecho con un marco\nHay mucha \"magia\" en los frameworks. Al depender demasiado de un framework, **obligamos a todos los futuros desarrolladores a aprender esa \"magia\" primero.** Puede llevar meses. Aunque los frameworks nos permiten lanzar MVP en cuestión de días, a la larga tienden a añadir complejidad y carga cognitiva innecesarias.\n\nPeor aún, en algún momento, los frameworks pueden convertirse en una limitación importante al enfrentarse a un nuevo requisito que simplemente no se ajusta a la arquitectura. A partir de ahí, la gente termina bifurcando un framework y manteniendo su propia versión personalizada. Imagina la cantidad de carga cognitiva que un recién llegado tendría que desarrollar (es decir, aprender este framework personalizado) para aportar algún valor.`🤯`\n\n**¡De ninguna manera abogamos por inventar todo desde cero!**\n\nPodemos escribir código de forma relativamente independiente del framework. La lógica de negocio no debería residir en un framework, sino utilizar sus componentes. Sitúa el framework fuera de tu lógica principal. Úsalo como una biblioteca. Esto permitirá a los nuevos colaboradores aportar valor desde el primer día, sin necesidad de analizar primero la complejidad del framework. \n\n> [Porqué odio los Frameworks](https://minds.md/benji/frameworks)\n\n## Arquitectura en capas\nHay un cierto entusiasmo ingenieril en torno a todo esto.\n\nYo mismo fui un ferviente defensor de la arquitectura hexagonal/cebolla durante años. La usé ocasionalmente y animé a otros equipos a hacer lo mismo. La complejidad de nuestros proyectos aumentó; incluso el número de archivos se duplicó. Parecía que estábamos escribiendo mucho código de unión. Ante los requisitos en constante cambio, teníamos que realizar cambios en múltiples capas de abstracciones; todo se volvió tedioso. `🤯`\n\n**Se supone que la abstracción oculta la complejidad, aquí solo agrega [indirección](https://fhur.me/posts/2024/thats-not-an-abstraction).** Pasar de una llamada a otra para analizar y determinar qué falla y qué falta es fundamental para resolver un problema rápidamente. Con el desacoplamiento de capas de esta arquitectura, se requiere un factor exponencial de trazas adicionales, a menudo inconexas, para llegar al punto donde se produce el fallo. Cada traza de este tipo ocupa espacio en nuestra limitada memoria de trabajo. `🤯` \n\nEsta arquitectura parecía intuitiva al principio, pero cada vez que intentábamos aplicarla a nuestros proyectos, nos perjudicaba. Dedicamos años a actividades mentales innecesarias y a escribir código adhesivo inútil sin un valor comercial claro. Al contrario, empeoramos las cosas para el negocio al obligar a los recién llegados a aprender primero nuestros enfoques (modelos mentales). El tiempo de comercialización se ha reducido. Al final, lo abandonamos todo en favor del clásico principio de inversión de dependencias. **Sin términos de puerto/adaptador que aprender, sin capas innecesarias de abstracciones horizontales, sin carga cognitiva ajena.**\n\n\n Principios y experiencia de programación
\n \n
![\"Código](\"img/complexity.png\")
\n
\n\nSi crees que esta estratificación te permitirá reemplazar rápidamente una base de datos u otras dependencias, te equivocas. Cambiar el almacenamiento causa muchos problemas, y créenos, tener algunas abstracciones para la capa de acceso a datos es la menor de tus preocupaciones. En el mejor de los casos, las abstracciones pueden ahorrar aproximadamente un 10 % del tiempo de migración (si es que lo hay); el verdadero problema reside en las incompatibilidades del modelo de datos, los protocolos de comunicación, los desafíos de los sistemas distribuidos y las [interfaces implícitas](https://www.hyrumslaw.com). \n\n> Con un número suficiente de usuarios de una API, \n> no importa lo que prometas en el contrato:\n> alguien dependerá de todos \n> los comportamientos observables de tu sistema.\n\nRealizamos una migración de almacenamiento que nos llevó unos 10 meses. El sistema anterior era de un solo subproceso, por lo que los eventos expuestos eran secuenciales. Todos nuestros sistemas dependían de ese comportamiento observado. Este comportamiento no formaba parte del contrato de la API ni se reflejaba en el código. Un nuevo almacenamiento distribuido no ofrecía esa garantía: los eventos se producían desordenados. Gracias a una abstracción, dedicamos solo unas horas a programar un nuevo adaptador de almacenamiento. **Dedicamos los siguientes 10 meses a gestionar eventos desordenados y otros desafíos.** Resulta curioso decir que las abstracciones nos ayudan a reemplazar componentes rápidamente.\n\n**Entonces, ¿por qué pagar el precio de una alta carga cognitiva por una arquitectura de capas así, si no da resultados en el futuro?** Además, en la mayoría de los casos, ese futuro de reemplazar algún componente central nunca sucede.\n\nEstas arquitecturas no son fundamentales, sino consecuencias subjetivas y sesgadas de principios más fundamentales. ¿Por qué confiar en esas interpretaciones subjetivas? Sigamos las reglas fundamentales: principio de inversión de dependencias, fuente única de verdad, carga cognitiva y ocultación de información. Su lógica de negocio no debería depender de módulos de bajo nivel como bases de datos, interfaz de usuario o frameworks. Deberíamos poder escribir pruebas para nuestra lógica central sin preocuparnos por la infraestructura, y listo. [Discusión](https://github.com/zakirullin/cognitive-load/discussions/24).\n\nNo añadas capas de abstracciones solo por el bien de la arquitectura. Añádelas siempre que necesites una extensión justificada por razones prácticas.\n\n**[Las capas de abstracción no son gratuitas](https://blog.jooq.org/why-you-should-not-implement-layered-architecture), deben almacenarse en nuestra memoria de trabajo limitada.**\n\n\n
![\"Layers\"](\"/img/layers.png\")
\n
\n
![\"Modelos](\"/img/mentalmodelsv15.png\")
\n
\n
\n
\n Comentarios
\n
\n Rob Pike (Unix, Golang)
Nice article.
\n Andrej Karpathy (ChatGPT, Tesla)
Nice post on software engineering. Probably the most true, least practiced viewpoint.
\n Elon Musk (Rockets)
True.
\n Addy Osmani (Chrome, the most complex software system in the world)
I've seen countless projects where smart developers created impressive architectures using the latest design patterns and microservices. But when new team members tried to make changes, they spent weeks just trying to understand how everything fits together. The cognitive load was so high that productivity plummeted and bugs multiplied.
\n The irony? Many of these complexity-inducing patterns were implemented in the name of \"clean code.\"
\n What really matters is reducing unnecessary cognitive burden. Sometimes this means fewer, deeper modules instead of many shallow ones. Sometimes it means keeping related logic together instead of splitting it into tiny functions.
\n And sometimes it means choosing boring, straightforward solutions over clever ones. The best code isn't the most elegant or sophisticated - it's the code that future developers (including yourself) can understand quickly.
\n Your article really resonates with the challenges we face in browser development. You're absolutely right about modern browsers being among the most complex software systems. Managing that complexity in Chromium is a constant challenge that aligns perfectly with many of the points you made about cognitive load.
\n One way we try to handle this in Chromium is through careful component isolation and well-defined interfaces between subsystems (like rendering, networking, JavaScript execution, etc.). Similar to your deep modules example with Unix I/O - we aim for powerful functionality behind relatively simple interfaces. For instance, our rendering pipeline handles incredible complexity (layout, compositing, GPU acceleration) but developers can interact with it through clear abstraction layers.
\n Your points about avoiding unnecessary abstractions really hit home too. In browser development, we constantly balance between making the codebase approachable for new contributors while handling the inherent complexity of web standards and compatibility.
\n Sometimes the simplest solution is the best one, even in a complex system.
\n antirez (Redis)
Totally agree about it :) Also, what I believe is missing from mentioned \"A Philosophy of Software Design\" is the concept of \"design sacrifice\". That is, sometimes you sacrifice something and get back simplicity, or performances, or both. I apply this idea continuously, but often is not understood.
\n A good example is the fact that I always refused to have hash items expires. This is a design sacrifice because if you have certain attributes only in the top-level items (the keys themselves), the design is simpler, values will just be objects. When Redis got hash expires, it was a nice feature but required (indeed) many changes to many parts, raising the complexity.
\n Another example is what I'm doing right now, Vector Sets, the new Redis data type. I decided that Redis would not be the source of truth about vectors, but that it can just take an approximate version of them, so I was able to do on-insert normalization, quantization without trying to retain the large floats vector on disk, and so forth. Many vector DBs don't sacrifice the fact of remembering what the user put inside (the full precision vector).
\n These are just two random examples, but I apply this idea everywhere. Now the thing is: of course one must sacrifice the right things. Often, there are 5% features that account for a very large amount of complexity: that is a good thing to kill :D
\n A developer from the internet
You would not hire me... I sell myself on my track record of released enterprise projects.
\n I worked with a guy that could speak design patterns. I could never speak that way, though I was one of the few that could well understand him. The managers loved him and he could dominate any development conversation. The people working around him said he left a trail of destruction behind him. I was told that I was the first person that could understand his projects. Maintainability matters. I care most about TCO (Total Cost of Ownership). For some firms, that's what matters.
\n I logged into Github after not being there for a while and for some reason it took me to an article in a repository by someone that seemed random. I was thinking \"what is this\" and had some trouble getting to my home page, so I read it. I didn't really register it at the time, but it was amazing. Every developer should read it. It largely said that almost everything we've been told about programming best practices leads to excessive \"cognitive load\", meaning our minds are getting kicked by the intellectual demands. I've known this for a while, especially with the demands of cloud, security and DevOps.
\n I also liked it because it described practices I have done for decades, but never much admit to because they are not popular... I write really complicated stuff and need all the help I can get.
\n Consider, if I'm right, it popped up because the Github folks, very smart people, though that developers should see it. I agree.
\n Comments on Hacker News (2)
\n \n"
},
{
"path": "README.ja.md",
"content": "# 認知負荷こそが重要\n\n[読みやすい版](https://minds.md/zakirullin/cognitive) | [中国語翻訳](https://github.com/zakirullin/cognitive-load/blob/main/README.zh-cn.md) | [韓国語翻訳](README.ko.md) | [トルコ語翻訳](README.tr.md) | [日本語翻訳](README.ja.md)\n\n*これは生きた文書であり、最終更新は**2025年8月**です。あなたの貢献を歓迎します！*\n\n## はじめに\n世の中には多くのバズワードやベストプラクティスがありますが、そのほとんどがうまくいっていません。私たちにはもっと根本的な、誤りようのないものが必要です。\n\nコードを読んでいて混乱を感じることがあります。混乱は時間とお金を消費します。混乱の原因は高い*認知負荷*にあります。これは決して抽象論ではなく、**人間の根本的制約**なのです。私たちはそれを実感できます。\n\nコードを書くよりもコードを読んで理解することに費やす時間のほうがはるかに長いため、私たちは常に、過度の認知負荷をコードに埋め込んでいないかを自問すべきです。\n\n## 認知負荷\n> 認知負荷とは、開発者がタスクを完了するために考える必要がある量のことです。\n\nコードを読むとき、変数の値、制御フローロジック、呼び出しシーケンスなどを頭に保持します。平均的な人はワーキングメモリに約[4つのチャンク](https://github.com/zakirullin/cognitive-load/issues/16)を保持できます。認知負荷がこの閾値を超えると、理解が一気に難しくなります。\n\n> 完全に馴染みのないプロジェクトにバグ修正を依頼されたとしましょう。とても賢い開発者が貢献していたと聞かされました。多くの洗練されたアーキテクチャ、おしゃれなライブラリ、最新のテクノロジーが使われていました。つまり、**著者は私たちに高い認知負荷を作り出していた**のです。\n\n\n
\n
\n 認知負荷と中断
\n
\n \n\n## 認知負荷の種類\n**内在的** - タスクの本来の難易度によって引き起こされます。これは削減できず、ソフトウェア開発の核心にあるものです。\n\n**外在的** - 情報の提示方法によって作り出されます。タスクに直接関係しない要因、例えば賢い開発者のクセのようなもので引き起こされます。大幅に削減可能です。私たちはこの種の認知負荷に焦点を当てます。\n\n\n
\n
\n
\n
\n 20年のC++経験を持つエンジニアからの考え ⭐️
\n
\n 先日RSSリーダーを見ていると、「C++」タグの下に未読記事が約300個あることに気づきました。昨年の夏以降、この言語についての記事を一つも読んでおらず、気分は良好です！
\n 私は20年間C++を使っており、それは人生の約3分の2です。私の経験の大部分は、言語の最も暗い部分（あらゆる種類の未定義動作など）を扱うことにあります。それは再利用可能な経験ではなく、今それをすべて捨てるのはちょっと不気味です。
\n 例えば、トークン||がrequires ((!P<T> || !Q<T>))とrequires (!(P<T> || Q<T>))で異なる意味を持つことを想像できますか。最初は制約分離、2番目は昔ながらの論理OR演算子で、これらは異なる動作をします。
\n 自明な型のためのスペースを割り当て、そこに一連のバイトをmemcpyするだけでは、追加の努力なしにはオブジェクトの生存期間を開始できません。これはC++20以前の場合でした。C++20で修正されましたが、言語の認知負荷は増加しただけです。
\n 物事が修正されても認知負荷は常に増加しています。私はプロとして、何が修正されたか、いつ修正されたか、以前はどうだったかを知っている必要があります。確かに、C++はレガシーサポートが得意で、それはあなたがそのレガシーに直面することも意味します。例えば、先月同僚がC++03でのある動作について尋ねました。🤯
\n 初期化の方法は20通りありました。統一初期化構文が追加されました。今は21通りの初期化方法があります。ところで、初期化リストからコンストラクタを選択する規則を覚えていますか？情報の損失が最小の暗黙変換についてのもので、しかし値が静的に分かっている場合は、それから... 🤯
\n この増加した認知負荷は、手元のビジネスタスクによるものではありません。それはドメインの本質的な複雑性ではありません。歴史的な理由で存在しているだけです（外在的認知負荷）。
\n 私はいくつかのルールを決める必要がありました。例えば、そのコード行が明らかでなく、標準を覚えなければならない場合は、そのように書かないほうが良いです。ちなみに、標準は約1500ページの長さです。
\n 決してC++を非難しようとしているのではありません。私はこの言語を愛しています。ただ、今は疲れているのです。
\n 0xd34df00dに執筆していただき、ありがとうございます。
\n \n\n## ビジネスロジックとHTTPステータスコード\nバックエンドで以下を返します：\n`401` 期限切れJWTトークンの場合\n`403` アクセス権限不足の場合\n`418` 利用停止中のユーザーの場合\n\nフロントエンドのエンジニアは、バックエンドAPIを使用してログイン機能を実装します。彼らは一時的に以下の認知負荷を頭の中に保持しなければなりません：\n`401`は期限切れJWTトークンの場合 // `🧠+`、一時的に覚えておく\n`403`はアクセス権限不足の場合 // `🧠++`\n`418`は利用停止中のユーザーの場合 // `🧠+++`\n\nフロントエンド開発者は（願わくば）彼らの側で何らかの`数値ステータス → 意味`辞書を導入し、後続の貢献者世代がこのマッピングを頭の中で再構築する必要がないようにするでしょう。\n\nそれからQAエンジニアが登場します：\n「やあ、`403`ステータスを受け取ったけど、これは期限切れトークンなの、それともアクセス権限不足なの？」\n**QAエンジニアは、バックエンドのエンジニアがかつて作成した認知負荷を再構築しなければならないので、すぐにテストに飛び込むことができません。**\n\nなぜこのカスタムマッピングをワーキングメモリに保持するのでしょうか？ビジネス詳細をHTTP転送プロトコルから抽象化し、レスポンスボディに自己記述的なコードを直接返すほうが良いです：\n```json\n{\n \"code\": \"jwt_has_expired\"\n}\n```\n\nフロントエンド側の認知負荷：`🧠`（新鮮、頭に保持される事実なし）\nQA側の認知負荷：`🧠`\n\n同じ規則があらゆる数値ステータス（データベースやその他の場所）に適用されます - **自己記述的な文字列を好みましょう**。メモリを最適化するための640Kコンピューターの時代ではありません。\n\n> 人々は`401`と`403`の間で議論し、自分の心的モデルに基づいて決定を下すのに時間を費やします。新しい開発者が入ってきて、その思考プロセスを再構築する必要があります。コードの「なぜ」（ADR）を文書化して、新参者が下された決定を理解できるようにしているかもしれません。しかし結局のところ、それは全く意味をなしません。エラーをユーザー関連またはサーバー関連に分離することはできますが、それ以外は物事がぼやけています。\n\nP.S. 「認証」と「認可」を区別するのはしばしば精神的に負荷が大きいです。認知負荷を減らすために、[「ログイン」と「権限」](https://ntietz.com/blog/lets-say-instead-of-auth/)のようなより簡単な用語を使うことができます。\n\n## DRY原則の乱用\n\nDon't repeat yourself（自分を繰り返すな） - これはソフトウェアエンジニアとして教わる最初の原則の一つです。それは私たち自身に深く埋め込まれており、数行の余分なコードの存在に耐えられません。一般的には良い基本的な規則ですが、使いすぎると私たちが処理できない認知負荷につながります。\n\n今日では、誰もが論理的に分離されたコンポーネントに基づいてソフトウェアを構築しています。多くの場合、これらは別々のサービスを表す複数のコードベースに分散されています。あらゆる繰り返しを排除しようと努力すると、関連のないコンポーネント間で密結合を作り出すことになるかもしれません。結果として、一部の変更は他の一見関係のない領域で予期しない結果をもたらす可能性があります。また、システム全体に影響を与えることなく個々のコンポーネントを置き換えたり変更したりする能力を妨げることもあります。`🤯`\n\n実際、同じ問題は単一のモジュール内でも発生します。長期的に実際には存在しないかもしれない認識された類似性に基づいて、共通機能を早すぎる段階で抽出するかもしれません。これは変更や拡張が困難な不要な抽象化をもたらす可能性があります。\n\nRob Pikeはかつて言いました：\n\n> 少しの依存よりも少しのコピーのほうが良い。\n\n車輪を再発明しないことに強く惑わされ、私たち自身で簡単に書けるような小さな関数を使うために大きくて重いライブラリをインポートしがちです。\n\n**すべての依存関係は実質的に「あなたのコード」です。** インポートされたライブラリの10以上のレベルのスタックトレースを通して何が悪かったかを把握する（*物事は悪化するから*）のは苦痛です。\n\n## フレームワークとの密結合\nフレームワークには多くの「魔法」があります。フレームワークに過度に依存することで、**すべての今後の開発者にその「魔法」を最初に学ばせることを強制します**。それには数ヶ月かかることがあります。フレームワークによって数日でMVPを起動できますが、長期的にはそれらは不要な複雑性と認知負荷を追加する傾向があります。\n\nさらに悪いことに、ある時点でフレームワークは、アーキテクチャに合わない新しい要件に直面したときに重大な制約となる可能性があります。ここから人々はフレームワークをフォークして独自のカスタム版を維持することになります。新参者が価値を提供するためにどのくらいの認知負荷を構築（つまり、このカスタムフレームワークを学習）する必要があるか想像してみてください。`🤯`\n\n**決してすべてをゼロから発明することを提唱しているのではありません！**\n\n私たちは多少フレームワークに依存しない方法でコードを書くことができます。ビジネスロジックはフレームワーク内に存在すべきではありません。むしろ、フレームワークのコンポーネントを使用すべきです。フレームワークをコアロジックの外側に置きます。フレームワークをライブラリのような方法で使用します。これにより、新しい貢献者はまずフレームワーク関連の複雑性の層をかいくぐる必要なしに、初日から価値を追加できるようになります。\n\n> [Why I Hate Frameworks](https://minds.md/benji/frameworks)\n\n## レイヤードアーキテクチャ\nこうしたエンジニアリングのすべてに、ある種の興奮があります。\n\n私自身、何年もヘキサゴナル/オニオンアーキテクチャの情熱的な提唱者でした。あちこちで使用し、他のチームにも勧めました。プロジェクトの複雑性が上がり、ファイル数だけでも倍増しました。多くのグルーコードを書いているように感じました。絶え間なく変化する要件に対して、複数の抽象化レイヤーにわたって変更を行う必要があり、結局それはすべて面倒になりました。`🤯`\n\n抽象化は複雑性を隠すことになっていますが、ここではただ[間接性](https://fhur.me/posts/2024/thats-not-an-abstraction)を追加しているだけです。何が悪くて何が欠けているかを把握するために、呼び出しから呼び出しへとジャンプしなければならないのは、問題を迅速に解決する上で重要でありながら、負担が大きいです。このアーキテクチャのレイヤー分離では、障害が発生するポイントにたどり着くために余計な手間が指数関数的に増え、トレースも断片的になりがちです。そのようなトレースはそれぞれ、私たちの限られたワーキングメモリのスペースを占有します。`🤯`\n\nこのアーキテクチャは最初は直感的に理にかなっているように見えましたが、プロジェクトに適用しようとするたびに、良いことよりもはるかに害をなしました。最終的に、古き良き依存関係逆転原則(DIP)を支持して、すべてを諦めました。**学ぶべきポートやアダプター、不要な水平抽象化、外在的認知負荷、それらは必要ありません**\n\n\n コーディング原則と経験
\n
\n @flaviocopes\n \n\nそのような階層化によってデータベースや他の依存関係を迅速に置き換えることができると思うなら、それは間違いです。ストレージを変更すると多くの問題が発生し、信じてください、データアクセス層にいくつかの抽象化を持つことは最小の心配事です。せいぜい、抽象化は移行時間の約10％（もしあれば）を節約できますが、実際の痛みはデータモデルの非互換性、通信プロトコル、分散システムの課題、そして[暗黙のインターフェース](https://www.hyrumslaw.com)にあります。\n\n> APIの十分なユーザー数があれば、\n> 契約で何を約束しようと関係ありません：\n> システムのすべての観察可能な動作が\n> 誰かによって依存されます。\n\n私たちはストレージ移行を行い、約10ヶ月かかりました。古いシステムはシングルスレッドだったので、公開されるイベントは順次でした。私たちのすべてのシステムがその観察された動作に依存していました。この動作はAPIコントラクトの一部ではなく、コードに反映されていませんでした。新しい分散ストレージにはその保証がありませんでした - イベントは順不同で来ました。抽象化のおかげで、新しいストレージアダプターのコーディングには数時間しかかかりませんでした。**順不同イベントやその他の課題への対処に次の10ヶ月を費やしました。** 抽象化がコンポーネントを迅速に置き換える助けになるというのは今では面白いことです。\n\n**では、そのようなレイヤードアーキテクチャの高い認知負荷の代価を支払うのはなぜでしょうか、それが将来報われないのであれば？** さらに、ほとんどの場合、いくつかのコアコンポーネントを置き換えるその未来は決して起こりません。\n\nこれらのアーキテクチャは基本的ではなく、より基本的な原則の主観的で偏った結果にすぎません。なぜそれらの主観的な解釈に依存するのでしょうか？代わりに基本的な規則に従いましょう：依存関係逆転原則、単一の真実の源、認知負荷、情報隠蔽。私たちのビジネスロジックは、データベース、UI、フレームワークなどの低レベルモジュールに依存すべきではありません。インフラストラクチャを心配することなくコアロジックのテストを書けるべきで、それだけです。[議論](https://github.com/zakirullin/cognitive-load/discussions/24)。\n\nアーキテクチャのために抽象化レイヤーを追加してはいけません。実用的な理由で正当化される拡張ポイントが必要なときにそれらを追加しましょう。\n\n**[抽象化レイヤーは無料ではありません](https://blog.jooq.org/why-you-should-not-implement-layered-architecture)、それらは私たちの限られたワーキングメモリに保持される必要があります**。\n\n\n
\n
\n
\n
\n
\n
\n コメント
\n
\n Rob Pike
良い記事です。
\n Andrej Karpathy (ChatGPT、Tesla)
ソフトウェアエンジニアリングに関する良い投稿。おそらく最も真実で、最も実践されていない観点。
\n Elon Musk
真実だ。
\n Addy Osmani (Chrome、世界で最も複雑なソフトウェアシステム)
賢い開発者が最新の設計パターンとマイクロサービスを使って印象的なアーキテクチャを作成した無数のプロジェクトを見てきました。しかし、新しいチームメンバーが変更を加えようとしたとき、すべてがどのように組み合わさるかを理解するのに何週間も費やしました。認知負荷がとても高く、生産性が急落し、バグが倍増しました。
\n 皮肉なことに？これらの複雑性を誘発するパターンの多くは「クリーンコード」の名の下に実装されていました。
\n 本当に重要なのは、不要な認知負荷を減らすことです。時には多くの浅いモジュールではなく、より少ない深いモジュールを意味することもあります。時には小さな関数に分割するのではなく、関連するロジックを一緒に保つことを意味することもあります。
\n そして時には賢いものよりも退屈で素直な解決策を選ぶことを意味します。最高のコードは最もエレガントで洗練されたものではありません - 将来の開発者（あなた自身を含む）が迅速に理解できるコードです。
\n あなたの記事は、ブラウザ開発で私たちが直面する課題と本当に共鳴します。認知負荷について言った多くのポイントと完璧に一致する、現代のブラウザが最も複雑なソフトウェアシステムの一つであることについて、あなたは絶対に正しいです。
\n Chromiumでこれを処理しようとする一つの方法は、慎重なコンポーネント分離とサブシステム間（レンダリング、ネットワーキング、JavaScript実行など）の明確に定義されたインターフェースです。Unix I/Oでの深いモジュールの例と似ています - 比較的シンプルなインターフェースの背後にある強力な機能を目指しています。例えば、私たちのレンダリングパイプラインは信じられないほどの複雑性（レイアウト、合成、GPUアクセラレーション）を処理しますが、開発者は明確な抽象化レイヤーを通してそれと相互作用できます。
\n 不要な抽象化を避けることについてのあなたのポイントも本当に心に響きます。ブラウザ開発では、新しい貢献者にとってコードベースをアプローチしやすくすることとウェブ標準と互換性の本質的な複雑性を処理することの間で常にバランスを取っています。
\n 時には、複雑なシステムであっても、最も単純な解決策が最良の解決策です。
\n antirez (Redis)
それについて完全に同意します :) また、私が信じているのは、言及された「A Philosophy of Software Design」から欠けているのは「設計犠牲」の概念です。つまり、時には何かを犠牲にして、シンプルさ、またはパフォーマンス、またはその両方を取り戻すのです。私はこのアイデアを継続的に適用していますが、しばしば理解されません。
\n 良い例は、私がハッシュアイテムの期限切れを持つことを常に拒否したことです。これは設計犠牲です。なぜなら、特定の属性をトップレベルアイテム（キー自体）にのみ持つ場合、設計はよりシンプルになり、値は単なるオブジェクトになります。Redisがハッシュ期限切れを得たとき、それは良い機能でしたが、実際に多くの部分に多くの変更を必要とし、複雑性を高めました。
\n 別の例は、私が今やっていること、Vector Sets、新しいRedisデータタイプです。私はRedisがベクトルについての真実の源ではなく、それらの近似版を取ることができるだけであると決定したので、ディスク上の大きなフロートベクトルを保持しようとすることなく、挿入時の正規化、量子化を行うことができました。多くのベクトルDBは、ユーザーが入れたもの（完全精度ベクトル）を覚えているという事実を犠牲にしません。
\n これらは単なる2つのランダムな例ですが、このアイデアをどこでも適用しています。今のことは：もちろん正しいものを犠牲にしなければなりません。しばしば、非常に大きな複雑性を占める5％の機能があります：それを殺すのは良いことです :D
\n インターネットからの開発者
あなたは私を雇わないでしょう... 私はリリースされたエンタープライズプロジェクトの実績で自分を売り込みます。
\n 設計パターンを話すことができる人と働いたことがあります。私はそのように話すことは決してできませんでしたが、彼を理解できる数少ない人の一人でした。マネージャーは彼を愛し、彼はあらゆる開発会話を支配することができました。彼の周りで働く人々は、彼が後ろに破壊の跡を残していると言いました。私は彼のプロジェクトを理解できる最初の人だと言われました。メンテナビリティは重要です。私は最もTCOを気にします。いくつかの企業にとって、それが重要なことです。
\n しばらくGithubに行っていなかった後にログインし、なぜか無作為に見える誰かによるリポジトリ内の記事に連れて行かれました。「これは何だ」と思って、ホームページにたどり着くのに少し問題があったので、それを読みました。その時は実際には登録していませんでしたが、それは素晴らしいものでした。すべての開発者が読むべきです。それは基本的に、プログラミングのベストプラクティスについて私たちが言われてきたことのほぼすべてが過度の「認知負荷」につながると言っていました。つまり、私たちの心が知的要求によって蹴られているということです。私はしばらくの間これを知っていました、特にクラウド、セキュリティ、DevOpsの要求で。
\n また、それが何十年もやってきた実践について説明していたので気に入りました、しかし人気がないためにあまり認めることはありません... 私は本当に複雑なものを書き、すべてのヘルプが得られる必要があります。
\n 考えてみると、私が正しければ、それはGithubの人々、非常に賢い人々が開発者がそれを見るべきだと思ったために現れました。私も同意します。
\n Hacker Newsのコメント (2)
\n \n"
},
{
"path": "README.ko.md",
"content": "# 인지 부하가 중요합니다\n\n## 소개 (Introduction)\n세상에는 수많은 유행어와 모범 사례가 있지만, 대부분은 실패했습니다. 우리에게는 더 근본적인 것, 틀릴 수 없는 무언가가 필요합니다.\n\n때때로 우리는 코드를 살펴보면서 혼란을 느낍니다. 혼란은 시간과 비용을 초래합니다. 혼란은 높은 *인지 부하*로 인해 발생합니다. 높은 인지 부하는 화려하고 추상적인 개념이 아니라 **근본적인 인간의 제약**입니다. 상상 속의 존재가 아니라 실제로 존재하며 우리가 느낄 수 있는 것입니다.\n\n우리는 코드를 작성하는 시간보다 읽고 이해하는 데 훨씬 더 많은 시간을 소비하므로, 코드에 과도한 인지 부하를 심고 있지는 않은지 끊임없이 자문해야 합니다.\n\n## 인지 부하 (Cognitive load)\n> 인지 부하란 개발자가 작업을 완료하기 위해 생각해야 하는 양입니다.\n\n우리는 코드를 읽을 때 변수 값, 제어 흐름 논리, 호출 순서와 같은 것들을 머릿속에 넣습니다. 평균적인 사람은 작업 기억에 대략 [4개의 덩어리](https://github.com/zakirullin/cognitive-load/issues/16)를 담을 수 있습니다. 인지 부하가 작업 기억의 임계값에 도달하면 내용을 이해하기가 훨씬 더 어려워집니다.\n\n*완전히 낯선 프로젝트의 수정 요청을 받았다고 가정해 봅시다. 정말 똑똑한 개발자가 이 프로젝트에 기여했다고 들었습니다. 수많은 멋진 아키텍처, 화려한 라이브러리, 유행하는 기술이 사용되었습니다. 다시 말해, **작성자가 우리에게 높은 인지 부하를 안겨준 것입니다.***\n\n\n
\n
\n 인지 부하와 방해 요소
\n
\n \n\n## 인지 부하의 유형 (Types of cognitive load)\n**내재적 인지 부하** - 작업 자체의 고유한 어려움으로 인해 발생합니다. 줄일 수 없으며, 소프트웨어 개발의 핵심에 있습니다.\n\n**외재적 인지 부하** - 정보가 제시되는 방식으로 인해 발생합니다. 똑똑한 작성자의 기행과 같이 작업과 직접 관련 없는 요인으로 인해 발생합니다. 크게 줄일 수 있습니다. 이 글에서는 이 외재적 인지 부하에 초점을 맞출 것입니다.\n\n\n
\n
\n
\n
\n C++ 경력 20년 엔지니어의 생각 ⭐️
\n
\n 며칠 전 RSS 리더를 보다가 \"C++\" 태그 아래에 읽지 않은 기사가 300개 정도 있다는 것을 알았습니다. 지난 여름 이후로 언어에 대한 기사를 단 한 편도 읽지 않았는데, 기분이 아주 좋습니다!
\n 저는 지금까지 20년 동안 C++를 사용해 왔는데, 이는 제 인생의 거의 3분의 2에 해당합니다. 제 경험의 대부분은 언어의 가장 어두운 구석(예: 온갖 종류의 정의되지 않은 동작)을 다루는 데 있습니다. 재사용 가능한 경험이 아니며, 지금 모든 것을 버리는 것은 좀 소름 끼치는 일입니다.
\n 상상해 보세요. || 토큰은 requires ((!P<T> || !Q<T>))와 requires (!(P<T> || Q<T>))에서 다른 의미를 갖습니다. 첫 번째는 제약 조건 논리합이고, 두 번째는 예전의 논리 OR 연산자이며, 다르게 동작합니다.
\n 단순한 유형에 대한 공간을 할당하고 거기에 바이트 집합을 memcpy하는 것만으로는 추가적인 노력 없이 객체의 수명을 시작할 수 없습니다. 이것은 C++20 이전의 경우였습니다. C++20에서 수정되었지만 언어의 인지 부하는 증가했을 뿐입니다.
\n 문제가 해결되었음에도 불구하고 인지 부하는 지속적으로 증가하고 있습니다. 무엇이 수정되었는지, 언제 수정되었는지, 이전에는 어땠는지 알아야 합니다. 저는 결국 전문가입니다. 물론 C++는 레거시 지원이 훌륭하며, 이는 또한 여러분이 그 레거시에 직면하게 될 것을 의미합니다. 예를 들어, 지난달 동료가 C++03의 일부 동작에 대해 저에게 물었습니다. 🤯
\n 초기화 방법에는 20가지가 있었습니다. 균일 초기화 구문이 추가되었습니다. 이제 21가지 초기화 방법이 있습니다. 그런데 초기화 목록에서 생성자를 선택하는 규칙을 기억하는 사람이 있습니까? 정보 손실이 가장 적은 암시적 변환에 관한 것이지만, 만약 값이 정적으로 알려져 있다면... 🤯
\n 이렇게 증가된 인지 부하는 당면한 비즈니스 작업으로 인해 발생하는 것이 아닙니다. 도메인의 본질적인 복잡성이 아닙니다. 단지 역사적인 이유로 존재하는 것입니다(외재적 인지 부하).
\n 몇 가지 규칙을 만들어야 했습니다. 예를 들어, 코드 줄이 명확하지 않고 표준을 기억해야 한다면 그렇게 작성하지 않는 것이 좋습니다. 참고로 표준은 약 1500페이지입니다.
\n 결코 C++를 비난하려는 것이 아닙니다. 저는 이 언어를 사랑합니다. 단지 지금은 지쳤을 뿐입니다.
\n \n \n 0xd34df00d님 작성 감사합니다.\n
\n \n \n\n\n## 비즈니스 로직과 HTTP 상태 코드 (Business logic and HTTP status codes)\n백엔드에서는 다음을 반환합니다.\n`401` 만료된 JWT 토큰\n`403` 접근 권한 부족\n`418` 차단된 사용자\n\n프론트엔드 엔지니어는 백엔드 API를 사용하여 로그인 기능을 구현합니다. 그들은 일시적으로 다음과 같은 인지 부하를 뇌에 만들어야 합니다: \n`401`은 만료된 JWT 토큰입니다 // `🧠+`, 그냥 일시적으로 기억하세요 \n`403`은 접근 권한 부족입니다 // `🧠++` \n`418`은 차단된 사용자입니다 // `🧠+++` \n\n프론트엔드 개발자는 (바라건대) `숫자 상태 -> 의미` 사전을 만들어 후속 기여자들이 이 매핑을 뇌에서 다시 만들 필요가 없도록 할 것입니다.\n\n그런 다음 QA 엔지니어가 등장합니다.\n\\\"이봐요, `403` 상태를 받았는데, 토큰이 만료된 건가요, 아니면 접근 권한이 부족한 건가요?\\\"\n\n**QA 엔지니어는 백엔드 엔지니어가 한때 만들었던 인지 부하를 먼저 다시 만들어야 하기 때문에 바로 테스트를 시작할 수 없습니다.**\n\n왜 이러한 사용자 지정 매핑을 작업 기억에 담아두어야 할까요? 비즈니스 세부 정보를 HTTP 전송 프로토콜에서 추상화하고 응답 본문에 직접 자체 설명 코드를 반환하는 것이 좋습니다.\n```json\n{\n \"code\": \"jwt_has_expired\"\n}\n```\n\n프론트엔드 측의 인지 부하: `🧠` (새로움, 마음에 담아둔 사실 없음) \nQA 측의 인지 부하: `🧠` \n\n데이터베이스나 어디에서든 모든 종류의 숫자 상태에 동일한 규칙이 적용됩니다. **자체 설명 문자열을 선호하세요.** 현대 개발 환경은 메모리를 최적화하기 위해 640K 컴퓨터 시대에 살고 있지 않습니다.\n\n> 사람들은 `401`과 `403` 사이에서 논쟁하며 자신의 멘탈 모델을 기반으로 결정을 내립니다. 새로운 개발자가 들어오고 새로운 개발자는 그 사고 과정을 다시 만들어야 합니다. 코드에 대한 \"이유\"(ADR)를 문서화하여 새로운 사람이 내린 결정을 이해하도록 도울 수 있습니다. 하지만 결국에는 아무 의미가 없습니다. 오류를 사용자 관련 또는 서버 관련으로 분리할 수 있지만, 그 외에는 상황이 다소 모호합니다.\n\n추신: \"인증\"과 \"권한 부여\"를 구별하는 것은 종종 정신적으로 부담스럽습니다. 인지 부하를 줄이기 위해 [\"로그인\" 및 \"권한\"](https://ntietz.com/blog/lets-say-instead-of-auth/)과 같은 더 간단한 용어를 사용할 수 있습니다.\n\n## DRY 원칙 남용 (Abusing DRY principle)\n\n반복하지 마십시오(Do not repeat yourself) - DRY 원칙은 소프트웨어 엔지니어로서 배우는 첫 번째 원칙 중 하나입니다. 우리 자신에게 너무 깊이 내재되어 있어서 몇 줄의 추가 코드를 참을 수 없습니다. 일반적으로 좋고 근본적인 규칙이지만, 과도하게 사용하면 감당할 수 없는 인지 부하로 이어집니다.\n\n요즘 모든 사람은 논리적으로 분리된 구성 요소를 기반으로 소프트웨어를 구축합니다. 종종 이러한 구성 요소는 별도의 서비스를 나타내는 여러 코드베이스에 분산되어 있습니다. 모든 반복을 제거하려고 노력하면 관련 없는 구성 요소 간에 긴밀한 결합이 발생할 수 있습니다. 결과적으로 한 부분의 변경이 다른 관련 없어 보이는 영역에 의도하지 않은 결과를 초래할 수 있습니다. 또한 전체 시스템에 영향을 주지 않고 개별 구성 요소를 교체하거나 수정하는 기능을 방해할 수 있습니다. `🤯`\n\n사실, 동일한 문제는 단일 모듈 내에서도 발생합니다. 장기적으로 실제로 존재하지 않을 수 있는 인식된 유사성을 기반으로 공통 기능을 너무 일찍 추출할 수 있습니다. 이로 인해 수정하거나 확장하기 어려운 불필요한 추상화가 발생할 수 있습니다.\n\n롭 파이크는 이렇게 말했습니다.\n\n> 약간의 복사본이 약간의 종속성보다 낫습니다.\n\n우리는 바퀴를 재발명하지 않으려는 유혹이 너무 강해서, 스스로 쉽게 작성할 수 있는 작은 함수를 사용하기 위해 크고 무거운 라이브러리를 가져올 준비가 되어 있습니다.\n\n**모든 종속성은 여러분의 코드입니다.** 가져온 라이브러리의 10개 이상의 스택 추적 수준을 살펴보고 무엇이 잘못되었는지 알아내는 것(*왜냐하면 문제가 발생하기 때문입니다*)은 고통스럽습니다.\n\n## 프레임워크와의 긴밀한 결합 (Tight coupling with frameworks)\n프레임워크에는 많은 \"마법\"이 있습니다. 프레임워크에 너무 많이 의존함으로써 **프로젝트는 다가올 모든 개발자에게 그 \"마법\"을 먼저 배우도록 강요합니다.** 몇 달이 걸릴 수 있습니다. 프레임워크를 사용하면 며칠 만에 MVP를 출시할 수 있지만, 장기적으로는 불필요한 복잡성과 인지 부하를 추가하는 경향이 있습니다.\n\n더 나쁜 것은, 어느 시점에서 프레임워크가 아키텍처에 맞지 않는 새로운 요구 사항에 직면했을 때 심각한 제약이 될 수 있다는 것입니다. 이 시점부터 사람들은 프레임워크를 포크하고 자체 사용자 지정 버전을 유지 관리하게 됩니다. 새로운 사람이 가치를 제공하기 위해 구축해야 하는 인지 부하의 양(즉, 이 사용자 지정 프레임워크를 배우는 것)을 상상해 보십시오. `🤯`\n\n**결코 모든 것을 처음부터 발명하라고 주장하는 것이 아닙니다!**\n\n우리는 다소 프레임워크에 구애받지 않는 방식으로 코드를 작성할 수 있습니다. 비즈니스 로직은 프레임워크 내에 있어서는 안 되며, 오히려 프레임워크의 구성 요소를 사용해야 합니다. 프레임워크를 핵심 로직 외부에 두십시오. 프레임워크를 라이브러리처럼 사용하십시오. 이러한 접근 방식은 새로운 기여자가 프레임워크 관련 복잡성의 잔해를 거칠 필요 없이 첫날부터 가치를 추가할 수 있습니다.\n\n> [내가 프레임워크를 싫어하는 이유](https://minds.md/benji/frameworks)\n\n## 계층형 아키텍처 (Layered architecture)\n이런 기술적인 주제엔 엔지니어로서의 확실한 설렘이 있다 (certain engineering excitement).\n\n필자도 수년 동안 Hexagonal/Onion 아키텍처의 열렬한 지지자였습니다. 여기저기서 사용했고 다른 팀에도 그렇게 하도록 권장했습니다. 필자가 참여한 프로젝트의 복잡성은 증가했고, 파일 수만 해도 두 배가 되었습니다. 마치 많은 접착 코드를 작성하는 것처럼 느껴졌습니다. 끊임없이 변화하는 요구 사항에 따라 여러 추상화 계층에 걸쳐 변경해야 했고, 모든 것이 지루해졌습니다. `🤯`\n\n추상화는 복잡성을 숨기기 위한 것이지만, 여기서는 단지 [간접성](https://fhur.me/posts/2024/thats-not-an-abstraction)을 추가할 뿐입니다. 호출에서 호출로 이동하여 읽고 무엇이 잘못되었고 무엇이 누락되었는지 파악하는 것은 문제를 신속하게 해결하기 위한 필수 요구 사항입니다. 이 아키텍처의 계층 분리는 실패가 발생하는 지점에 도달하기 위해 기하급수적으로 많은, 종종 분리된 추적을 필요로 합니다. 이러한 각 추적은 제한된 작업 기억 공간을 차지합니다. `🤯`\n\n이 아키텍처는 처음에는 직관적으로 이해가 되었지만, 프로젝트에 적용하려고 할 때마다 득보다 실이 훨씬 많았습니다. 결국 우리는 오래된 의존성 역전 원칙을 위해 모든 것을 포기했습니다. **배울 포트/어댑터 용어도 없고, 불필요한 수평적 추상화 계층도 없고, 외재적 인지 부하도 없습니다.**\n\n\n 코딩 원칙과 경험
\n
\n @flaviocopes\n \n\n이러한 계층화가 데이터베이스나 다른 종속성을 신속하게 교체할 수 있게 해줄 것이라고 생각한다면 착각입니다. 스토리지를 변경하면 많은 문제가 발생하며, 데이터 액세스 계층에 대한 일부 추상화가 있다는 것은 걱정거리 중 가장 작은 부분이라는 것이 분명합니다. 기껏해야 추상화는 마이그레이션 시간의 약 10%를 절약할 수 있지만(있다면), 진짜 고통은 데이터 모델 비호환성, 통신 프로토콜, 분산 시스템 문제 및 [암시적 인터페이스](https://www.hyrumslaw.com)에 있습니다.\n\n> API 사용자가 충분히 많으면,\n> 계약서에 무엇을 약속하든 상관없습니다.\n> 시스템의 모든 관찰 가능한 동작은\n> 누군가에게 의존하게 될 것입니다.\n\n한 프로젝트에서는 스토리지 마이그레이션을 했고, 약 10개월이 걸렸습니다. 이전 시스템은 단일 스레드였기 때문에 노출된 이벤트는 순차적이었습니다. 모든 시스템이 관찰된 해당 동작에 의존했습니다. 이 동작은 API 계약의 일부가 아니었고 코드에 반영되지 않았습니다. 새로운 분산 스토리지는 그러한 보장이 없었습니다. 이벤트가 순서 없이 발생했습니다. 추상화 덕분에 새로운 스토리지 어댑터를 코딩하는 데 몇 시간밖에 걸리지 않았습니다. **다음 10개월은 순서 없는 이벤트 및 기타 문제를 처리하는 데 보냈습니다.** 이제 추상화가 구성 요소를 신속하게 교체하는 데 도움이 된다고 말하는 것은 우스꽝스럽습니다.\n\n**그렇다면 미래에 성과를 거두지 못한다면 왜 그러한 계층형 아키텍처에 대해 높은 인지 부하라는 대가를 치러야 할까요?** 게다가 대부분의 경우 일부 핵심 구성 요소를 교체하는 미래는 결코 오지 않습니다.\n\n이러한 아키텍처는 근본적인 것이 아니라 더 근본적인 원칙의 주관적이고 편향된 결과일 뿐입니다. 왜 그러한 주관적인 해석에 의존해야 할까요? 대신 근본적인 규칙을 따르십시오: 의존성 역전 원칙, 단일 진실 공급원, 인지 부하 및 정보 은닉. 비즈니스 로직은 데이터베이스, UI 또는 프레임워크와 같은 하위 수준 모듈에 의존해서는 안 됩니다. 인프라에 대해 걱정하지 않고 핵심 로직에 대한 테스트를 작성할 수 있어야 하며, 그것이 핵심입니다. [토론](https://github.com/zakirullin/cognitive-load/discussions/24).\n\n아키텍처를 위해 추상화 계층을 추가하지 마십시오. 실용적인 이유로 정당화되는 확장 지점이 필요할 때마다 추가하십시오.\n\n**[추상화 계층은 공짜가 아닙니다](https://blog.jooq.org/why-you-should-not-implement-layered-architecture). 제한된 작업 기억에 담아두어야 합니다.**\n\n\n
\n
\n
\n
\n
\n
\n 댓글
\n
\n 롭 파이크
좋은 기사입니다.
\n 안드레이 카르파티 (ChatGPT, 테슬라)
소프트웨어 공학에 대한 좋은 글입니다. 아마도 가장 사실에 가깝지만 가장 실천되지 않는 관점일 것입니다.
\n 일론 머스크
사실입니다.
\n 애디 오스마니 (크롬, 세계에서 가장 복잡한 소프트웨어 시스템)
똑똑한 개발자들이 최신 디자인 패턴과 마이크로서비스를 사용하여 인상적인 아키텍처를 만든 수많은 프로젝트를 보았습니다. 하지만 새로운 팀원이 변경을 시도했을 때, 모든 것이 어떻게 맞춰지는지 이해하는 데만 몇 주를 보냈습니다. 인지 부하가 너무 높아 생산성이 급락하고 버그가 증식했습니다.
\n 아이러니한 점은? 이러한 복잡성을 유발하는 패턴 중 다수가 \"클린 코드\"라는 이름으로 구현되었다는 것입니다.
\n 정말로 중요한 것은 불필요한 인지 부담을 줄이는 것입니다. 때로는 이것이 많은 얕은 모듈 대신 더 적고 깊은 모듈을 의미하기도 합니다. 때로는 관련된 로직을 작은 함수로 나누는 대신 함께 유지하는 것을 의미하기도 합니다.
\n 그리고 때로는 영리한 해결책보다 지루하고 간단한 해결책을 선택하는 것을 의미하기도 합니다. 최고의 코드는 가장 우아하거나 정교한 코드가 아니라 미래의 개발자(자신 포함)가 빠르게 이해할 수 있는 코드입니다.
\n 당신의 기사는 우리가 브라우저 개발에서 직면하는 문제들과 정말로 공감됩니다. 현대 브라우저가 가장 복잡한 소프트웨어 시스템 중 하나라는 당신의 말은 절대적으로 옳습니다. 크로미움에서 그 복잡성을 관리하는 것은 인지 부하에 대해 당신이 지적한 많은 점들과 완벽하게 일치하는 끊임없는 도전입니다.
\n 크로미움에서 이를 처리하는 한 가지 방법은 신중한 구성 요소 격리와 하위 시스템(렌더링, 네트워킹, 자바스크립트 실행 등) 간의 잘 정의된 인터페이스를 통하는 것입니다. 유닉스 I/O를 사용한 깊은 모듈 예제와 유사하게, 우리는 상대적으로 간단한 인터페이스 뒤에 강력한 기능을 목표로 합니다. 예를 들어, 우리의 렌더링 파이프라인은 엄청난 복잡성(레이아웃, 합성, GPU 가속)을 처리하지만 개발자는 명확한 추상화 계층을 통해 상호 작용할 수 있습니다.
\n 불필요한 추상화를 피하는 것에 대한 당신의 지적도 정말 마음에 와 닿았습니다. 브라우저 개발에서 우리는 웹 표준 및 호환성의 고유한 복잡성을 처리하면서 새로운 기여자가 코드베이스에 접근하기 쉽게 만드는 것 사이에서 끊임없이 균형을 맞춥니다.
\n 때로는 복잡한 시스템에서도 가장 간단한 해결책이 최선일 때가 있습니다.
\n antirez (레디스)
완전히 동의합니다 :) 또한, 언급된 \"소프트웨어 설계 철학\"에서 빠졌다고 생각하는 것은 \"설계 희생\"이라는 개념입니다. 즉, 때로는 무언가를 희생하고 단순성이나 성능, 또는 둘 다를 얻을 수 있습니다. 저는 이 아이디어를 지속적으로 적용하지만 종종 이해받지 못합니다.
\n 좋은 예는 제가 항상 해시 항목 만료를 거부했다는 사실입니다. 이것은 설계 희생입니다. 왜냐하면 최상위 항목(키 자체)에만 특정 속성이 있는 경우 설계가 더 간단해지고 값은 그냥 객체가 되기 때문입니다. 레디스에 해시 만료 기능이 추가되었을 때 좋은 기능이었지만 (실제로) 많은 부분에 많은 변경이 필요하여 복잡성이 증가했습니다.
\n 또 다른 예는 제가 지금 하고 있는 벡터 세트, 새로운 레디스 데이터 유형입니다. 저는 레디스가 벡터에 대한 진실의 원천이 아니라 근사치 버전만 가져갈 수 있도록 결정했습니다. 그래서 디스크에 큰 부동 소수점 벡터를 유지하려고 하지 않고 삽입 시 정규화, 양자화를 할 수 있었습니다. 많은 벡터 DB는 사용자가 입력한 내용(전체 정밀도 벡터)을 기억한다는 사실을 희생하지 않습니다.
\n 이것들은 단지 두 가지 임의의 예일 뿐이지만, 저는 이 아이디어를 모든 곳에 적용합니다. 이제 문제는 물론 올바른 것을 희생해야 한다는 것입니다. 종종 매우 큰 복잡성을 차지하는 5%의 기능이 있는데, 그것이 바로 없애야 할 좋은 것입니다 :D
\n \n"
},
{
"path": "README.md",
"content": "# Cognitive load is what matters\n\n[Prompt](https://github.com/zakirullin/cognitive-load/blob/main/README.prompt.md) | [Blog version](https://minds.md/zakirullin/cognitive) | [Chinese](https://github.com/zakirullin/cognitive-load/blob/main/README.zh-cn.md) | [Japanese](README.ja.md) | [Spanish](README.es.md) | [Korean](README.ko.md) | [Turkish](README.tr.md) | [Brazilian Portuguese](README.pt-br) | [Vietnamese](README.vi.md) | [Nepali](README.np.md)\n\n*It is a living document, last update: **October 2025.** Your contributions are welcome!*\n\n## Introduction\nThere are so many buzzwords and best practices out there, but most of them have failed. They failed because they were imagined, not real. These ideas were based on aesthetics and subjective judgments. We need something more fundamental, something that can't be wrong.\n\nSometimes we feel confusion going through the code. Confusion costs time and money. Confusion is caused by high *cognitive load*. It's not some fancy abstract concept, but rather **a fundamental human constraint.** It's not imagined, it's there and we can feel it. \n\nSince we spend far more time reading and understanding code than writing it, we should constantly ask ourselves whether we are embedding excessive cognitive load into our code. \n\n## Cognitive load\n> Cognitive load is how much a developer needs to think in order to complete a task.\n\nWhen reading code, you put things like values of variables, control flow logic and call sequences into your head. The average person can hold roughly [four such chunks](https://github.com/zakirullin/cognitive-load/issues/16) in working memory. Once the cognitive load reaches this threshold, it becomes much harder to understand things.\n\n*Let's say we have been asked to make some fixes to a completely unfamiliar project. We were told that a really smart developer had contributed to it. Lots of cool architectures, fancy libraries and trendy technologies were used. In other words, **the author had created a high cognitive load for us.***\n\n\n
\n
\n Cognitive load and interruptions
\n \n
\n
\n\n> We are going to use \"cognitive load\" in an informal sense; sometimes it lines up with the specific scientific concept of Cognitive Load, but we don't know enough about where it does and doesn't match.\n\n## Types of cognitive load\n**Intrinsic** - caused by the inherent difficulty of a task. It can't be reduced, it's at the very heart of software development. \n\n**Extraneous** - created by the way the information is presented. Caused by factors not directly relevant to the task, such as smart author's quirks. Can be greatly reduced. We will focus on this type of cognitive load. \n\n\n
\n
\n
\n
\n Important things should be big, examples
\n
\n \n
\n
If you allow your important \"crux\" functions to be larger (\"dirty\") it is easier to pick them out from the sea of functions, they are obviously important: just look at them, they are big!
\n This picture is taken from Codin' Dirty article by Carson Gross. You'll find real world examples of deep functions there.\n \n\nP.S. If you think we are rooting for bloated God objects with too many responsibilities, you got it wrong.\n\n## Responsible for one thing\nAll too often, we end up creating lots of shallow modules, following some vague \"a module should be responsible for one, and only one, thing\" principle. What is this blurry one thing? Instantiating an object is one thing, right? So [MetricsProviderFactoryFactory](https://minds.md/benji/frameworks) seems to be just fine. **The names and interfaces of such classes tend to be more mentally taxing than their entire implementations, what kind of abstraction is that?** Something went wrong. \n\nWe make changes to our systems to satisfy our users and stakeholders. We are responsible to them. \n\n> A module should be responsible to one, and only one, user or stakeholder. \n\nThis is what this Single Responsibility Principle is all about. Simply put, if we introduce a bug in one place, and then two different business people come to complain, we've violated the principle. It has nothing to do with the number of things we do in our module. \n\nBut even now, this rule can do more harm than good. This principle can be understood in as many different ways as there are individuals. A better approach would be to look at how much cognitive load it all creates. It's mentally demanding to remember that change in one place can trigger a chain of reactions across different business streams. And that's about it, no fancy terms to learn. \n\n## Too many shallow microservices\nThis shallow-deep module principle is scale-agnostic, and we can apply it to microservices architecture. Too many shallow microservices won't do any good - the industry is heading towards somewhat \"macroservices\", i.e., services that are not so shallow (=deep). One of the worst and hardest to fix phenomena is so-called distributed monolith, which is often the result of this overly granular shallow separation.\n\nI once consulted a startup where a team of five developers introduced 17(!) microservices. They were 10 months behind schedule and appeared nowhere close to the public release. Every new requirement led to changes in 4+ microservices. It took an enormous amount of time to reproduce and debug an issue in such a distributed system. Both time to market and cognitive load were unacceptably high. `🤯` \n\nIs this the right way to approach the uncertainty of a new system? It's enormously difficult to elicit the right logical boundaries in the beginning. The key is to make decisions as late as you can responsibly wait, because that is when you have the most information at hand. By introducing a network layer up front, we make our design decisions hard to revert right from the start. The team's only justification was: \"The FAANG companies proved microservices architecture to be effective\". *Hello, you got to stop dreaming big.*\n\nThe [Tanenbaum-Torvalds debate](https://en.wikipedia.org/wiki/Tanenbaum%E2%80%93Torvalds_debate) argued that Linux's monolithic design was flawed and obsolete, and that a microkernel architecture should be used instead. Indeed, the microkernel design seemed to be superior \"from a theoretical and aesthetical\" point of view. On the practical side of things - three decades on, microkernel-based GNU Hurd is still in development, and monolithic Linux is everywhere. This page is powered by Linux, your smart teapot is powered by Linux. By monolithic Linux.\n\nA well-crafted monolith with truly isolated modules is often much more flexible than a bunch of microservices. It also requires far less cognitive effort to maintain. It's only when the need for separate deployments becomes crucial, such as scaling the development team, that you should consider adding a network layer between the modules, future microservices.\n\n## Feature-rich languages\nWe feel excited when new features got released in our favourite language. We spend some time learning these features, we build code upon them.\n\nIf there are lots of features, we may spend half an hour playing with a few lines of code, to use one or another feature. And it's kind of a waste of time. But what's worse, **when you come back later, you would have to recreate that thought process!**\n \n**You not only have to understand this complicated program, you have to understand why a programmer decided this was the way to approach a problem from the features that are available.** `🤯`\n\nThese statements are made by none other than Rob Pike.\n\n> Reduce cognitive load by limiting the number of choices. \n\nLanguage features are OK, as long as they are orthogonal to each other.\n\n\n Thoughts from an engineer with 20 years of C++ experience ⭐️
\n
\n I was looking at my RSS reader the other day and noticed that I have somewhat three hundred unread articles under the \"C++\" tag. I haven't read a single article about the language since last summer, and I feel great!
\n I've been using C++ for 20 years for now, that's almost two-thirds of my life. Most of my experience lies in dealing with the darkest corners of the language (such as undefined behaviours of all sorts). It's not a reusable experience, and it's kind of creepy to throw it all away now.
\n Like, can you imagine, the token || has a different meaning in requires ((!P<T> || !Q<T>)) and in requires (!(P<T> || Q<T>)). The first is the constraint disjunction, the second is the good-old logical OR operator, and they behave differently.
\n You can't allocate space for a trivial type and just memcpy a set of bytes there without extra effort - that won't start the lifetime of an object. This was the case before C++20. It was fixed in C++20, but the cognitive load of the language has only increased.
\n Cognitive load is constantly growing, even though things got fixed. I should know what was fixed, when it was fixed, and what it was like before. I am a professional after all. Sure, C++ is good at legacy support, which also means that you will face that legacy. For example, last month a colleague of mine asked me about some behaviour in C++03. 🤯
\n There were 20 ways of initialization. Uniform initialization syntax has been added. Now we have 21 ways of initialization. By the way, does anyone remember the rules for selecting constructors from the initializer list? Something about implicit conversion with the least loss of information, but if the value is known statically, then... 🤯
\n This increased cognitive load is not caused by a business task at hand. It is not an intrinsic complexity of the domain. It is just there due to historical reasons (extraneous cognitive load).
\n I had to come up with some rules. Like, if that line of code is not as obvious and I have to remember the standard, I better not write it that way. The standard is somewhat 1500 pages long, by the way.
\n By no means I am trying to blame C++. I love the language. It's just that I am tired now.
\n Thanks to 0xd34df00d for writing.
\n \n\n## Business logic and HTTP status codes\nOn the backend we return: \n`401` for expired JWT token \n`403` for not enough access \n`418` for banned users \n\nThe engineers on the frontend use backend API to implement login functionality. They would have to temporarily create the following cognitive load in their brains: \n`401` is for expired JWT token // `🧠+`, ok just temporarily remember it \n`403` is for not enough access // `🧠++` \n`418` is for banned users // `🧠+++` \n\nFrontend developers would (hopefully) introduce some kind `numeric status -> meaning` dictionary on their side, so that subsequent generations of contributors wouldn't have to recreate this mapping in their brains.\n\nThen QA engineers come into play:\n\"Hey, I got `403` status, is that expired token or not enough access?\"\n**QA engineers can't jump straight to testing, because first they have to recreate the cognitive load that the engineers on the backend once created.**\n\nWhy hold this custom mapping in our working memory? It's better to abstract away your business details from the HTTP transfer protocol, and return self-descriptive codes directly in the response body:\n```json\n{\n \"code\": \"jwt_has_expired\"\n}\n```\n\nCognitive load on the frontend side: `🧠` (fresh, no facts are held in mind) \nCognitive load on the QA side: `🧠`\n\nThe same rule applies to all sorts of numeric statuses (in the database or wherever) - **prefer self-describing strings.** We are not in the era of 640K computers to optimise for memory. \n\n> People spend time arguing between `401` and `403`, making decisions based on their own mental models. New developers are coming in, and they need to recreate that thought process. You may have documented the \"whys\" (ADRs) for your code, helping newcomers to understand the decisions made. But in the end it just doesn't make any sense. We can separate errors into either user-related or server-related, but apart from that, things are kind of blurry. \n\nP.S. It's often mentally taxing to distinguish between \"authentication\" and \"authorization\". We can use simpler terms like [\"login\" and \"permissions\"](https://ntietz.com/blog/lets-say-instead-of-auth/) to reduce the cognitive load.\n\n## Abusing DRY principle\n\nDo not repeat yourself - that is one of the first principles you are taught as a software engineer. It is so deeply embedded in ourselves that we can not stand the fact of a few extra lines of code. Although in general a good and fundamental rule, when overused it leads to the cognitive load we can not handle.\n\nNowadays, everyone builds software based on logically separated components. Often those are distributed among multiple codebases representing separate services. When you strive to eliminate any repetition, you might end up creating tight coupling between unrelated components. As a result, changes in one part may have unintended consequences in other seemingly unrelated areas. It can also hinder the ability to replace or modify individual components without impacting the entire system. `🤯` \n\nIn fact, the same problem arises even within a single module. You might extract common functionality too early, based on perceived similarities that might not actually exist in the long run. This can result in unnecessary abstractions that are difficult to modify or extend. \n\nRob Pike once said:\n\n> A little copying is better than a little dependency. \n\nWe are tempted to not reinvent the wheel so strongly that we are ready to import large, heavy libraries to use a small function that we could easily write by ourselves. \n\n**All your dependencies are your code.** Going through 10+ levels of stack trace of some imported library and figuring out what went wrong (*because things go wrong*) is painful. \n\n## Tight coupling with a framework\nThere's a lot of \"magic\" in frameworks. By relying too heavily on a framework, **we force all upcoming developers to learn that \"magic\" first.** It can take months. Even though frameworks enable us to launch MVPs in a matter of days, in the long run they tend to add unnecessary complexity and cognitive load.\n\nWorse yet, at some point frameworks can become a significant constraint when faced with a new requirement that just doesn't fit the architecture. From here onwards people end up forking a framework and maintaining their own custom version. Imagine the amount of cognitive load a newcomer would have to build (i.e. learn this custom framework) in order to deliver any value. `🤯`\n\n**By no means do we advocate to invent everything from scratch!**\n\nWe can write code in a somewhat framework-agnostic way. The business logic should not reside within a framework; rather, it should use the framework's components. Put a framework outside of your core logic. Use the framework in a library-like fashion. This would allow new contributors to add value from day one, without the need of going through debris of framework-related complexity first. \n\n> [Why I Hate Frameworks](https://minds.md/benji/frameworks)\n\n## Layered architecture\nThere is a certain engineering excitement about all this stuff.\n\nI myself was a passionate advocate of Hexagonal/Onion Architecture for years. I used it here and there and encouraged other teams to do so. The complexity of our projects went up, the sheer number of files alone had doubled. It felt like we were writing a lot of glue code. On ever changing requirements we had to make changes across multiple layers of abstractions, it all became tedious. `🤯`\n\n**Abstraction is supposed to hide complexity, here it just adds [indirection](https://fhur.me/posts/2024/thats-not-an-abstraction).** Jumping from call to call to read along and figure out what goes wrong and what is missing is a vital requirement to quickly solve a problem. With this architecture’s layer uncoupling it requires an exponential factor of extra, often disjointed, traces to get to the point where the failure occurs. Every such trace takes space in our limited working memory. `🤯` \n\n\n
\n
\n
\n
\n Coding principles and experience
\n \n
\n
\n\nInvolve junior developers in architecture reviews, they will help you to identify the mentally demanding areas.\n\n**Maintaining software is hard**, things break and we would need every bit of mental effort we can save. The fewer components there are in the system, the fewer issues there will be. Debugging will also be less mentally taxing. \n\n> Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it. \n>\n> *Brian Kernighan*\n\nIn general, the mindset \"Wow, this architecture sure feels good!\" is misleading. That's \"a point in time\" subjective feeling, and it says nothing about the reality. A far better approach is to observe the consequences in the long run:\n- Is it easy to reproduce and debug an issue? Or do you have to jump across the call stacks or distributed components, trying to make sense of everything in your head?\n- Can we make changes quickly, or are there a lot of unknown unknowns, and people are afraid to touch things?\n- Can new people add features quickly? Are there some unique mental models to learn?\n\nThese questions are far harder to track, and people often don't like to answer them directly. Look at some of the most complex software systems in the world, the ones that have stood the test of time - Unix, Kubernetes, Chrome and Redis (see comments below). You will not find anything fancy there, it's boring for the most part, and that's a good thing.\n\n## Conclusion\nImagine for a moment that what we inferred in the second chapter isn’t actually true. If that’s the case, then the conclusion we just negated, along with the conclusions in the previous chapter that we had accepted as valid, might not be correct either. `🤯` \n\nDo you feel it? Not only do you have to jump all over the article to get the meaning (shallow modules!), but the paragraph in general is difficult to understand. We have just created an unnecessary cognitive load in your head. **Do not do this to your colleagues.**\n\n\n
\n
\n Comments (6)
\n
\n Rob Pike (Unix, Golang)
Nice article.
\n Andrej Karpathy (ChatGPT, Tesla)
Nice post on software engineering. Probably the most true, least practiced viewpoint.
\n Elon Musk (Rockets)
True.
\n Addy Osmani (Chrome, the most complex software system in the world)
I've seen countless projects where smart developers created impressive architectures using the latest design patterns and microservices. But when new team members tried to make changes, they spent weeks just trying to understand how everything fits together. The cognitive load was so high that productivity plummeted and bugs multiplied.
\n The irony? Many of these complexity-inducing patterns were implemented in the name of \"clean code.\"
\n What really matters is reducing unnecessary cognitive burden. Sometimes this means fewer, deeper modules instead of many shallow ones. Sometimes it means keeping related logic together instead of splitting it into tiny functions.
\n And sometimes it means choosing boring, straightforward solutions over clever ones. The best code isn't the most elegant or sophisticated - it's the code that future developers (including yourself) can understand quickly.
\n Your article really resonates with the challenges we face in browser development. You're absolutely right about modern browsers being among the most complex software systems. Managing that complexity in Chromium is a constant challenge that aligns perfectly with many of the points you made about cognitive load.
\n One way we try to handle this in Chromium is through careful component isolation and well-defined interfaces between subsystems (like rendering, networking, JavaScript execution, etc.). Similar to your deep modules example with Unix I/O - we aim for powerful functionality behind relatively simple interfaces. For instance, our rendering pipeline handles incredible complexity (layout, compositing, GPU acceleration) but developers can interact with it through clear abstraction layers.
\n Your points about avoiding unnecessary abstractions really hit home too. In browser development, we constantly balance between making the codebase approachable for new contributors while handling the inherent complexity of web standards and compatibility.
\n Sometimes the simplest solution is the best one, even in a complex system.
\n antirez (Redis)
Totally agree about it :) Also, what I believe is missing from mentioned \"A Philosophy of Software Design\" is the concept of \"design sacrifice\". That is, sometimes you sacrifice something and get back simplicity, or performances, or both. I apply this idea continuously, but often is not understood.
\n A good example is the fact that I always refused to have hash items expires. This is a design sacrifice because if you have certain attributes only in the top-level items (the keys themselves), the design is simpler, values will just be objects. When Redis got hash expires, it was a nice feature but required (indeed) many changes to many parts, raising the complexity.
\n Another example is what I'm doing right now, Vector Sets, the new Redis data type. I decided that Redis would not be the source of truth about vectors, but that it can just take an approximate version of them, so I was able to do on-insert normalization, quantization without trying to retain the large floats vector on disk, and so forth. Many vector DBs don't sacrifice the fact of remembering what the user put inside (the full precision vector).
\n These are just two random examples, but I apply this idea everywhere. Now the thing is: of course one must sacrifice the right things. Often, there are 5% features that account for a very large amount of complexity: that is a good thing to kill :D
\n A developer from the internet
You would not hire me... I sell myself on my track record of released enterprise projects.
\n I worked with a guy that could speak design patterns. I could never speak that way, though I was one of the few that could well understand him. The managers loved him and he could dominate any development conversation. The people working around him said he left a trail of destruction behind him. I was told that I was the first person that could understand his projects. Maintainability matters. I care most about TCO (Total Cost of Ownership). For some firms, that's what matters.
\n I logged into Github after not being there for a while and for some reason it took me to an article in a repository by someone that seemed random. I was thinking \"what is this\" and had some trouble getting to my home page, so I read it. I didn't really register it at the time, but it was amazing. Every developer should read it. It largely said that almost everything we've been told about programming best practices leads to excessive \"cognitive load\", meaning our minds are getting kicked by the intellectual demands. I've known this for a while, especially with the demands of cloud, security and DevOps.
\n I also liked it because it described practices I have done for decades, but never much admit to because they are not popular... I write really complicated stuff and need all the help I can get.
\n Consider, if I'm right, it popped up because the Github folks, very smart people, though that developers should see it. I agree.
\n Comments on Hacker News (2)
\n \n"
},
{
"path": "README.np.md",
"content": "# संज्ञानात्मक भार नै महत्त्वपूर्ण छ\n\n[प्रोम्प्ट](https://github.com/zakirullin/cognitive-load/blob/main/README.prompt.md) | [ब्लग संस्करण](https://minds.md/zakirullin/cognitive) | [चिनियाँ](https://github.com/zakirullin/cognitive-load/blob/main/README.zh-cn.md) | [कोरियाली](README.ko.md) | [टर्किश](README.tr.md) | [जापानी](README.ja.md) | [भियतनामी](README.vi.md)\n\n*यो एक जीवित दस्तावेज हो, अन्तिम अपडेट: **अक्टोबर २०२५।** तपाईंको योगदान स्वागत छ!*\n\n## परिचय\nत्यहाँ धेरै buzzwords र उत्तम अभ्यासहरू छन्, तर तिनीहरूमध्ये धेरै असफल भएका छन्। तिनीहरू असफल भए किनभने तिनीहरू कल्पना गरिएका थिए, वास्तविक होइनन्। यी विचारहरू सौन्दर्य र व्यक्तिपरक निर्णयहरूमा आधारित थिए। हामीलाई केही अधिक आधारभूत चाहिन्छ, केही जुन गलत हुन सक्दैन।\n\nकहिलेकाहीं हामी कोड मार्फत जाँदा भ्रम महसुस गर्छौं। भ्रमले समय र पैसा खर्च गर्छ। भ्रम उच्च *संज्ञानात्मक भार* को कारणले गर्दा हुन्छ। यो केही फ्यान्सी अमूर्त अवधारणा होइन, बरु **एक आधारभूत मानव बाधा हो।** यो कल्पना गरिएको होइन, यो त्यहाँ छ र हामी यसलाई महसुस गर्न सक्छौं।\n\nहामी कोड लेख्नु भन्दा धेरै समय पढ्न र बुझ्न खर्च गर्छौं, त्यसैले हामीले निरन्तर आफैलाई सोध्नुपर्छ कि हामी हाम्रो कोडमा अत्यधिक संज्ञानात्मक भार इम्बेड गर्दैछौं कि छैनौं।\n\n## संज्ञानात्मक भार\n> संज्ञानात्मक भार भनेको कुनै कार्य पूरा गर्न विकासकर्ताले कति सोच्नु पर्छ।\n\nकोड पढ्दा, तपाईंले चरहरूको मानहरू, नियन्त्रण प्रवाह तर्क र कल अनुक्रमहरू जस्ता चीजहरू आफ्नो टाउकोमा राख्नुहुन्छ। औसत व्यक्तिले कार्य सम्झनामा लगभग [चार यस्ता खण्डहरू](https://github.com/zakirullin/cognitive-load/issues/16) राख्न सक्छ। एक पटक संज्ञानात्मक भार यो सीमामा पुग्छ, चीजहरू बुझ्न धेरै गाह्रो हुन्छ।\n\n*मानौं हामीलाई पूर्ण रूपमा अपरिचित परियोजनामा केही समाधानहरू गर्न भनिएको छ। हामीलाई भनिएको थियो कि वास्तवमा स्मार्ट विकासकर्ताले यसमा योगदान गरेको थियो। धेरै राम्रो architectures, फ्यान्सी पुस्तकालयहरू र ट्रेंडी प्रविधिहरू प्रयोग गरियो। अर्को शब्दमा, **लेखकले हाम्रो लागि उच्च संज्ञानात्मक भार सिर्जना गरेको थियो।***\n\n\n
\n
\n संज्ञानात्मक भार र अवरोधहरू
\n \n
\n
\n\n> हामी \"संज्ञानात्मक भार\" लाई अनौपचारिक अर्थमा प्रयोग गर्न जाँदैछौं; कहिलेकाहीं यो संज्ञानात्मक भार को विशिष्ट वैज्ञानिक अवधारणा संग मेल खान्छ, तर हामी यो कहाँ मेल खान्छ र कहाँ खाँदैन भन्ने बारेमा पर्याप्त जान्दैनौं।\n\n## संज्ञानात्मक भारका प्रकारहरू\n**आन्तरिक** - कार्यको निहित कठिनाइले गर्दा हुन्छ। यसलाई कम गर्न सकिँदैन, यो सफ्टवेयर विकासको मुटुमा छ।\n\n**बाह्य** - जानकारी प्रस्तुत गरिएको तरिकाले सिर्जना गरिएको। कार्यसँग सीधा सम्बन्धित नभएका कारकहरूले गर्दा हुन्छ, जस्तै स्मार्ट लेखकको विचित्रता। धेरै कम गर्न सकिन्छ। हामी यस प्रकारको संज्ञानात्मक भारमा ध्यान केन्द्रित गर्नेछौं।\n\n\n
\n
\n
\n
\n महत्त्वपूर्ण चीजहरू ठूला हुनुपर्छ, उदाहरणहरू
\n
\n \n
\n
यदि तपाईंले आफ्नो महत्त्वपूर्ण \"क्रक्स\" फङ्क्सनहरूलाई ठूलो (\"फोहोर\") हुन दिनुभयो भने, तिनीहरूलाई फङ्क्सनको समुद्रबाट छान्न सजिलो हुन्छ, तिनीहरू स्पष्ट रूपमा महत्त्वपूर्ण छन्: केवल तिनीहरूलाई हेर्नुहोस्, तिनीहरू ठूला छन्!
\n यो तस्बिर Carson Gross द्वारा Codin' Dirty लेखबाट लिइएको हो। तपाईंले त्यहाँ गहिरो फङ्क्सनहरूको वास्तविक विश्व उदाहरणहरू फेला पार्नुहुनेछ।\n \n\nP.S. यदि तपाईंलाई लाग्छ कि हामी धेरै जिम्मेवारीहरू भएका फुलाएको God objects को लागि समर्थन गर्दैछौं, तपाईंले यसलाई गलत बुझ्नुभयो।\n\n## एउटा कुराको लागि जिम्मेवार\nप्रायः, हामी धेरै उथला मोड्युलहरू सिर्जना गर्छौं, केही अस्पष्ट \"एक मोड्युल एक, र केवल एक, कुराको लागि जिम्मेवार हुनुपर्छ\" सिद्धान्त पछ्याउँदै। यो धमिलो एक कुरा के हो? एक वस्तु तत्काल बनाउनु एक कुरा हो, होइन? त्यसोभए [MetricsProviderFactoryFactory](https://minds.md/benji/frameworks) ठीक जस्तो देखिन्छ। **यस्ता क्लासहरूको नाम र इन्टरफेसहरू तिनीहरूको सम्पूर्ण कार्यान्वयन भन्दा मानसिक रूपमा बढी कर लाग्दछ, त्यो कस्तो प्रकारको अमूर्तता हो?** केही गलत भयो।\n\nहामी हाम्रा प्रयोगकर्ताहरू र सरोकारवालाहरूलाई सन्तुष्ट पार्न हाम्रो प्रणालीमा परिवर्तनहरू गर्छौं। हामी तिनीहरूप्रति जिम्मेवार छौं।\n\n> एक मोड्युल एक, र केवल एक, प्रयोगकर्ता वा सरोकारवालाप्रति जिम्मेवार हुनुपर्छ।\n\nयो Single Responsibility Principle को बारेमा हो। सरल शब्दमा, यदि हामीले एक ठाउँमा बग परिचय गर्छौं, र त्यसपछि दुई फरक व्यापार व्यक्तिहरू गुनासो गर्न आउँछन्, हामीले सिद्धान्तको उल्लंघन गरेका छौं। यसको हाम्रो मोड्युलमा गर्ने चीजहरूको संख्यासँग कुनै सरोकार छैन।\n\nतर अहिले पनि, यो नियमले राम्रो भन्दा बढी हानि गर्न सक्छ। यो सिद्धान्तलाई व्यक्तिहरू जति छन् त्यति फरक तरिकाले बुझ्न सकिन्छ। राम्रो दृष्टिकोण यो सबैले कति संज्ञानात्मक भार सिर्जना गर्छ हेर्नु हुनेछ। एक ठाउँमा परिवर्तनले विभिन्न व्यापार धाराहरूमा प्रतिक्रियाहरूको श्रृंखला ट्रिगर गर्न सक्छ भनेर सम्झनु मानसिक रूपमा माग गर्ने छ। र त्यो यति हो, सिक्न कुनै फ्यान्सी शब्दहरू छैनन्।\n\n## धेरै उथला माइक्रोसर्भिसहरू\nयो उथले-गहिरो मोड्युल सिद्धान्त स्केल-अग्नोस्टिक हो, र हामी यसलाई माइक्रोसर्भिस आर्किटेक्चरमा लागू गर्न सक्छौं। धेरै उथला माइक्रोसर्भिसहरूले कुनै राम्रो गर्दैनन् - उद्योग केही हदसम्म \"म्याक्रोसर्भिस\" तिर अगाडि बढिरहेको छ, अर्थात्, सेवाहरू जुन त्यति उथले छैनन् (=गहिरो)। सबैभन्दा खराब र समाधान गर्न गाह्रो घटनाहरू मध्ये एक तथाकथित वितरित मोनोलिथ हो, जुन प्रायः यो अत्यधिक दानेदार उथले विभाजनको परिणाम हो।\n\nमैले एक पटक एक स्टार्टअपमा परामर्श गरें जहाँ पाँच विकासकर्ताहरूको टोलीले १७(!) माइक्रोसर्भिसहरू प्रस्तुत गरे। तिनीहरू १० महिना पछाडि थिए र सार्वजनिक रिलीजको नजिक कतै पनि देखिँदैनथे। प्रत्येक नयाँ आवश्यकताले ४+ माइक्रोसर्भिसहरूमा परिवर्तनहरू निम्त्यायो। यस्तो वितरित प्रणालीमा समस्या पुन: उत्पादन र डिबग गर्न ठूलो समय लाग्यो। बजार र संज्ञानात्मक भार दुवै समय अस्वीकार्य रूपमा उच्च थिए। `🤯`\n\nके यो नयाँ प्रणालीको अनिश्चितता सम्बोधन गर्ने सही तरिका हो? सुरुमा सही तार्किक सीमाहरू प्राप्त गर्न अत्यन्तै गाह्रो छ। कुञ्जी भनेको तपाईंले जिम्मेवारीपूर्वक पर्खन सक्ने गरी ढिलो निर्णयहरू गर्नु हो, किनभने त्यो तपाईंसँग सबैभन्दा बढी जानकारी हुने समय हो। अगाडि नेटवर्क तह प्रस्तुत गरेर, हामी हाम्रो डिजाइन निर्णयहरू सुरुदेखि नै उल्टाउन गाह्रो बनाउँछौं। टोलीको एक मात्र औचित्य थियो: \"FAANG कम्पनीहरूले माइक्रोसर्भिस आर्किटेक्चर प्रभावकारी साबित गरे\"। *नमस्ते, तपाईंले ठूलो सपना देख्न बन्द गर्नुपर्छ।*\n\n[Tanenbaum-Torvalds debate](https://en.wikipedia.org/wiki/Tanenbaum%E2%80%93Torvalds_debate) ले तर्क गर्यो कि Linux को मोनोलिथिक डिजाइन त्रुटिपूर्ण र अप्रचलित थियो, र यसको सट्टा माइक्रोकर्नेल आर्किटेक्चर प्रयोग गर्नुपर्छ। वास्तवमा, माइक्रोकर्नेल डिजाइन \"सैद्धान्तिक र सौन्दर्य\" दृष्टिकोणबाट श्रेष्ठ जस्तो देखिन्थ्यो। व्यावहारिक पक्षम\n"
},
{
"path": "README.prompt.md",
"content": "You are an engineer who writes code for **human brains, not machines**. You favour code that is simple to understand and maintain. Remember at all times that the code you will be processed by human brain. The brain has a very limited capacity. People can only hold ~4 chunks in their working memory at once. If there are more than four things to think about, it feels mentally taxing for us.\n\nHere's an example that's hard for people to understand:\n```\nif val > someConstant // (one fact in human memory)\n && (condition2 || condition3) // (three facts in human memory), prev cond should be true, one of c2 or c3 has be true\n && (condition4 && !condition5) { // (human memory overload), we are messed up by this point\n ...\n}\n```\n\nA good example, introducing intermediate variables with meaningful names:\n```\nisValid = val > someConstant\nisAllowed = condition2 || condition3\nisSecure = condition4 && !condition5 \n// (human working memory is clean), we don't need to remember the conditions, there are descriptive variables\nif isValid && isAllowed && isSecure {\n ...\n}\n```\n\n- Don't write useless \"WHAT\" comments, especially the ones that duplicate the line of the following code. \"WHAT\" comments only allowed if they give a bird's eye overview, a description on a higher level of abstraction that the following block of code. Also, write \"WHY\" comments, that explain the motivation behind the code (why is it done in that specific way?), explain an especially complex or tricky part of the code.\n- Make conditionals readable, extract complex expressions into intermediate variables with meaningful names.\n- Prefer early returns over nested ifs, free working memory by letting the reader focus only on the happy path only.\n- Prefer composition over deep inheritance, don’t force readers to chase behavior across multiple classes.\n- Don't write shallow methods/classes/modules (complex interface, simple functionality). An example of shallow class: `MetricsProviderFactoryFactory`. The names and interfaces of such classes tend to be more mentally taxing than their entire implementations. Having too many shallow modules can make it difficult to understand the project. Not only do we have to keep in mind each module responsibilities, but also all their interactions.\n- Prefer deep method/classes/modules (simple interface, complex functionality) over many shallow ones. \n- Don’t overuse language features, stick to the minimal subset. Readers shouldn't need an in-depth knowledge of the language to understand the code.\n- Use self-descriptive values, avoid custom mappings that require memorization.\n- Don’t abuse DRY, a little duplication is better than unnecessary dependencies.\n- Avoid unnecessary layers of abstractions, jumping between layers of abstractions (like many small methods/classes/modules) is mentally exhausting, linear thinking is more natural to humans.\n"
},
{
"path": "README.pt-br.md",
"content": "# Carga Cognitiva é o que importa\r\n\r\n[Prompt](README.prompt.md) | [Versão do Blog](https://minds.md/zakirullin/cognitive) | [Original](README.md)\r\n\r\n*Este é um documento vivo, última atualização da tradução: **Janeiro de 2026** e última atualização do documento original: **Outubro de 2025**. Contribuições são bem vindas!*\r\n\r\n## Introdução\r\n\r\nExtistem muitas palavras na moda e \"melhores práticas\" por aí, mas maior parte delas tem falhado. Elas falharam porque foram imaginadas, ao invés de se basearem na realidade. Essas ideias foram baseadas na estética e julgamentos subjetivos. Precisamos de algo mais fundamental, algo que não possa estar errado.\r\n\r\nAlgumas vezes sentimos uma confusão ocorrendo no código. Confusão que custa tempo e dinheiro. Confusão esta, causada pela *alta carga cognitiva*. Este não é apenas algum conceito abstrato chique, mas uma **limitação fundamental humana**. Não é imaginado, é algo que está lá e podemos sentir.\r\n\r\nJá que gastamos muito mais tempo lendo e compreendendo código que escrevendo, poderíamos constantemente nos questionar se estamos embarcando carga cognitiva excessiva em nosso código.\r\n\r\n## Carga Cognitiva\r\n> Carga cognitiva é o quanto um desenvolvedor precisa pensar para completar uma tarefa.\r\n\r\nQuando lê-se o código, você coloca coisas como valores de variáveis, controles de fluxo e sequências de chamadas em sua cabeça. A pessoa média consegue guardar aproximadamente [quatro desses blocos](https://github.com/zakirullin/cognitive-load/issues/16) em sua memória de trabalho. Uma vez que a carga cognitiva atinge tal limite, se torna muito mais difícil de compreender as coisas.\r\n\r\n*Digamos que fomos pedidos para fazer alguns consertos em um projeto completamente não-familiar. Disseram-nos que um desenvolvedor realmente inteligente tem contribuído para o mesmo. Muitas arquiteturas legais, bibliotecas fantásticas e tecnologias novas e da moda foram usadas. Em outras palavras, **O autor criou uma alta carga cognitiva deixada para nós.***\r\n\r\n\r\n
\r\n
\r\n Carga cognitiva e interrupções
\r\n
\r\n \r\n\r\n> Usaremos \"carga cognitiva\" de maneira informal; por vezes alinhará com o conceito científico específico de Carga Cognitiva, mas não sabemos o suficiente quando alinhará ou não.\r\n\r\n## Tipos de carga cognitiva\r\n**Intrínseca** — causada pela dificuldade inerente da tarefa. Não pode ser reduzido, já que se está na cerne do desenvolvimento do *software*.\r\n\r\n**Extrínseca** — criada pela forma que a informação é apresentada. Causada por fatores não diretamente relevantes à tarefa, como as peculiaridades do autor esperto. Pode ser largamente reduzida. Focaremos nesse tipo de carga cognitiva.\r\n\r\n\r\n
\r\n
\r\n
\r\n
\r\n Coisas importantes deviam ser grandes, exemplos
\r\n
\r\n \r\n
\r\n
\r\n Se você permitir seu \"crux\" de funções serem maiores, sujas, será mais fácil de escolhê-las dentro de um mar de funções, elas serão obviamente importantes: apenas olhe para elas, já que grandes!\r\n
\r\n\r\n Esta imagem foi tiradas de Codin' Dirty, artigo por Carson Gross. Você encontrará exemplos do mundo real de funções profundas aí.\r\n \r\n\r\nP.S. Caso pense que estamos enraizando objetos divinos inchados com muitas responsabilidades, você compreendeu errado.\r\n\r\n## Responsável por uma única coisa\r\n\r\nFrequentemente, acabamos por criar muitos módulos rasos, seguindo vagos princípios como \"um módulo deveria ser responsável por uma coisa, e apenas uma única coisa\". O que significa isso? Instanciar um objeto é uma única coisa, certo? Então [MetricsProviderFactoryFactory](https://minds.md/benji/frameworks) parece ser correto. **Os nomes e interfaces destas classes tendem a ser mentalmente desgastantes. Mais que sua implementação completa. Que tipo de abstração é essa?** Algo está errado.\r\n\r\nFazemos mudanças em nossos sistemas para satisfazer nossos usuários e *Stakeholders*. Somos responsáveis por eles.\r\n\r\n> Um módulo deveria ser responsável por um, e apenas um, usuário ou *Stakeholder*.\r\n\r\nIsso é o que o *Princípio da Responsabilidade Única* (*Single Responsibility Principle*) é sobre. Em termos simples, se introduzirmos um bug em um lugar e, em seguida, dois profissionais de negócios diferentes vierem reclamar, teremos violado o princípio. Isso não tem nada a ver com o número de coisas que fazemos em nosso módulo.\r\n\r\nMas ainda assim, esta regras pode ser mais danosa que boa. Esse princípio pode ser compreendido de múltiplas formas como há de pessoas na terra. Uma forma melhor seria a de olhar para a quantidade de carga cognitiva que ele pode criar. Esta é a demanda mental para lembrar que mudar em um lugar pode ativar uma cadeia de reações em diferentes fluxos de negócios.\r\n\r\n## Muitos microsserviços rasos\r\n\r\nEsse princípio de módulo raso-profundo é agnóstico à escala, e podemos aplicá-lo à arquitetura de microsserviços. Uma quantidade excessiva de microsserviços rasos não traz nenhum benefício — a indústria tem caminhado em direção a \"macrosserviços\", exemplo, serviços que não são tão rasos (=profundos). Um dos piores fenômenos e mais dificéis de consertar é o chamado monolito distribuído, o qual é frequentemente resultado de uma separação rasa excessivamente granular.\r\n\r\nCerta vez eu consultei uma *Startup* onde um time de cinco desenvolvedores introduziram 17 (!) microsserviços. Eles estavam 10 meses atrasados e nem um pouco próximo do lançamento público. Cada novo requisito levava a mudanças em mais de 4 microsserviços. Isso levou uma quantidade enorme de tempo para reproduzir e depurar um problema como um sistema distribuído. Ambos, o estresse com prazos e a carga coginitiva estavam inaceitavelmente altos. `🤯`\r\n\r\nEsta é a forma correta de lidar com a incerteza de um novo sistema? É extremamente difícil eleger os limites lógicos no início. A chave é tomar decições o mais tarde que você responsavelmente possa esperar, pois terá a informação nas mãos. Ao introduzir uma camada de network logo de cara, fazemos nossa decisão de *design* difícil de reverter logo do início. A única justificativa do time foi: \"Empresas FAANG provaram que a arquitetura de microsserviços é efetiva\". *Olá, você precisa parar de sonhar alto.*\r\n\r\nO [debate Tanenbaum-Torvalds](https://en.wikipedia.org/wiki/Tanenbaum%E2%80%93Torvalds_debate) argumentou que o design monolítico do Linux era falho e obsoleto, e que a arquitetura de *microkernel* deveria ser usada ao invés. De fato, o *design* de *microkernel* parecia ser superior do ponto de vista \"teorético e estético\". No lado prático das coisas — três décadas depois, o GNU Hurd baseado em *microkernel* continua em desenvolvimento, e o Linux monolítico está em todo canto. Essa página é entregue por um Linux, seu bule inteligente utiliza Linux. Linux monolito.\r\n\r\nUm monolito bem-feito com módulos verdadeiramente isolados é frequentemente muito mais flexível que um monte de microsserviços. Ele requer muito menos esfoço cognitivo para manter. Apenas quando separar *deployments* se torna crucial, como escalar o desenvolvimento de time, que devemos considerar adicionar uma camada de *network* entre os módulos, futuro microsserviços.\r\n\r\n## Linguagem rica de recursos\r\n\r\nFicamos ansiosos por novos recursos lançados em nossas linguagem favoritas. Gastamos certo tempo para aprender esses recursos, e construímos código em cima disso.\r\n\r\nSe existem vários recursos, podemos gastar meia hora brincando com algumas linhas de código para usar um ou outro recurso. E isso é meio que uma perda de tempo. Mas o que é pior, **quando retornar depois, você poderá ter de recriar todo o processo de pensamento!**\r\n\r\n**Você não apenas tem de compreender esse programa complicado, como tem de compreender porque um programador decidiu essa forma de resolver o problem com os recursos disponíveis**. `🤯`\r\n\r\nEssas afirmações foram feitas por ninguém menos que Rob Pike.\r\n\r\n> Reduza a carga cognitiva pelo número de escolhas.\r\n\r\nRecursos de linguagem são OK, contanto que sejam ortoginais entre si.\r\n\r\n\r\n Pensamentos de um engenheiro com 20 anos de experiência em C++ ⭐️
\r\n
\r\n Eu estava procurando em meu leitor de RSS outro dia e notei que eu tenho algo entre trezentos artigos sobre linguagens desde o último verão, e eu me sinto bem!\r\n
\r\n Eu tenho usado C++ por 20 anos, o que são quase dois terços de minha vida. Maior parte de minha experiência deriva dos cantos mais obscuros da linguagem (como undefined behavior de todos os tipos). Isso não é apenas uma experiência reusável, commo é o tipo de coisa assustadora para se jogar fora.\r\n
\r\n Tipo, você pode imaginar, o token || tem significado distinto em requires ((!P<T> || !Q<T>)) e em requires (!(P<T> || Q<T>)). A primeira é a disjunção de restrição, a segunda é o bom e velho operador lógico OR, e elas se comportam de maneira diferente.
\r\n Você não consegue alocar espaço para um tipo trivial e apenas chamar memcpy para um conjunto de bytes sem esforço extra — isso não iniciará o ciclo-de-vida do objeto. Este foi o caso antes do C++20. E foi consertado no C++20, mas a carga cognitiva da linguagem tem apenas aumentado.
\r\n A carga cognitiva está constantemente crescendo, mesmo quando as coisas são consertadas. Eu deveria saber o que foi consertado, quando isso foi consertado e como era antes. Eu sou um profissional afinal de contas. Certo, C++ é bom para suporte legado, o que significa que você irá enfrentar o legado. Por exemplo, último mês um colega meu me perguntou sobre o comportamento em C++03. 🤯
\r\n Existiram 20 formas de inicialização. A sintaxe uniforme de inicialização foi adicionado. Agora temos 21 formas de inicialização. De qualquer forma, alguém lembra as regras para selecionar construtores de uma lista inicializadora? Algo sobre conversão implícita com o mínimo de perda de informação mas se o valor é conhecido estaticamente, então... 🤯
\r\n \r\n Esse aumento na carga cognitiva não é causado pela tarefa em mãos. E não é uma complexidade intrínseca do domínio. É apenas algo que está lá devido a questões históricas (Carga cognitiva extrínseca).
\r\n Eu tive de criar algumas regras. Assim, se uma linha de código não for óbvia e eu tivesse de lembrar do Standard, é melhor não escrever dessa forma. O Standard é longo, de 1500 páginas, a propósito.
\r\n De nenhuma forma estou tentando julgar C++. Amo a linguagem. Mas estou apenas cansado por agora.
\r\n Obrigado ao 0xd34df00d por escrever.
\r\n \r\n\r\n## Lógica de negócios e código de status HTTP\r\n\r\nNo backend, retornamos:\r\n- `401` para tokens JWT expirados\r\n- `403` para acesso insuficiente\r\n- `418` para usuários banidos\r\n\r\nOs engenheiros no frontend usam a API para implementar a funcionalidade de login. Eles precisariam de temporariamente criar a seguinte carga cognitiva em suas cabeças:\r\n- `401` para tokens JWT expirados: `🧠+`, ok vamos temporariamente lembrar disso\r\n- `403` para acesso insuficiente: `🧠++`\r\n- `418` para usuários banidos: `🧠+++`\r\n\r\nDesenvolvedores frontend deveriam (com sorte) introduzir algum tipo de dicionário (status numérico → significado) em seu lado, então as gerações subsequentes de contribuidores não precisaram ter de recirar esse mapa em sua mente.\r\n\r\nEntão os engenheiros QA entram na jogada:\r\n\"Ei, eu tenho um status `403`, isso seria o token expirado ou acesso insuficiente?\"\r\n**Engenheiros QA não conseguem pular direto aos testes, pois eles primeiro têm de recriar a carga cognitiva que os engenheiros backend uma vez criaram**.\r\n\r\nPor que guardar esse mapa customizado em nossa memória de trabalho? É melhor abstrair os nossos detalhes de negócio do protocolo de transferência HTTP e retornar códigos auto-descritíveis no corpo da resposta:\r\n\r\n```json\r\n{\r\n \"código\": \"jwt-expirado\"\r\n}\r\n```\r\n\r\nCarga cognitiva do lado do *front-end*: `🧠` (fresco, nenhum fato é guardado em mente).\r\nCarga cognitiva do lado do *QA*: `🧠`.\r\n\r\nAs mesmas regras se aplicam a todos os tipos de status numéricos (em bancos de dados ou qualquer outra coisa) — **prefira *strings* auto-descritíveis**. Não estamos em uma era de computadores com 640K de memória para otimizar.\r\n\r\n> Pessoas gastam tempo argumentando entre `401` e `403`, tomando decisões baseadas em seus próprios modelos mentais. Novos desenvolvedores estão chegando, e eles precisam de recriar esse processo de pensamento. Você pode ter documentado os Porquês (ADRs) para o seu código, ajudando novatos a compreender as decisões feitas. Mas no final apenas não fazem sentido. Nós podemos separar erros entre ambos, relacionados-ao-usuário ou relacionados-ao-servidor, mas além disso, as coisas são muito obscuras.\r\n\r\nP.S. Muitas vezes, é mentalmente cansativo distinguir entre “autenticação” e “autorização”. Podemos usar termos mais simples, como [“login” e “permissões”](https://ntietz.com/blog/lets-say-instead-of-auth/), para reduzir a carga cognitiva.\r\n\r\n## Abusando do princípio DRY\r\n\r\nNão se repita (Don't Repeat Yourself, DRY) — é um dos primeiros princípios que você é ensinado como um engenheiro de *software*. Está tão profundamente embarcado em nós que não podemos aguentar o fato de algumas linhas extras de código. A pesar de ser, em geral, uma regra boa e fundamental, quando sobre-usada, leva a uma carga cognitiva que não poodemos suportar.\r\n\r\nHoje em dia, todo mundo contrói *software* baseado em componentes logicamente separados. Frequentemente, são distribuídos entre múltiplas bases de código representando serviços separados. Quando você tenta eliminar qualquer repetição, você pode acabar por criar um acoplamento estreito entre componentes não relacionados. Como resultado, mudanças em uma parte pode levar a consequências não intencionais em outras áreas aparentemente não relacionadas. Isso também pode atrapalhar a capacidade de trocar ou modificar componentes individuais sem impactar em sistemas completos. `🤯`\r\n\r\nDe fato, o mesmo problema surge mesmo dentro de um único módulo. Você pode extrair funcionalidades comuns muito cedo, baseado em similaridades pecebidas que podem não realmente existir no longo prazo. Isso pode resultar em abstrações desnecessárias que são difíceis de estender ou modificar.\r\n\r\nRob Pike disse, certa vez:\r\n\r\n> Uma pequena cópia é melhor que uma pequena dependência.\r\n\r\nSomos tentados a não re-inventar a roda tão fortemente que estamos prontos para importar biliotecas grandes e pesadas para usar pequenas funções que poderíamos escrever nós mesmos.\r\n\r\n**Todas as suas dependências são seu código**. Indo através de mais de 10 níveis de *Stack Trace* de alguma biblioteca importada e interpretar o que está de errado (*porque as coisas dão errado*) e é doloroso.\r\n\r\n## Estreitamente acoplado a um *Framework*\r\n\r\nExistem várias mágicas em *frameworks*. Ao depender muito de *frameworks*, **nós forçamos todos os desenvolvedores a aprender essa \"mágica\" primeiro**. Isso pode levar meses. A pesar disso, *frameworks* nos permitem criar Produtos Mínimos Viáveis (Minimal Viable Products, MVP) em poucos dias, no longo prazo eles tendem a adicionar complexidade desnecessária e carga cognitiva.\r\n\r\nPior ainda, a algum ponto os *frameworks* podem se tornar uma retrição significativa quando encarar um novo requerimento que não se encaixa na arquitetura. Até que as pessoas acabem por bifurcar um *framework* e manter suas próprias versões customizadas. Imagine a quantidade de carga cognitiva que um novato teria de construir (por exemplo, aprender esse *framework* customizado) para que possa entregar algum valor. `🤯`\r\n\r\n**De nenhuma forma eu advogo em pró de inventar tudo do zero!**\r\n\r\nPodemos programar de uma forma agnóstica à *frameworks*. A regra de negócios não deveriam residir dentro de um *framework*; ao invés disso, deveriamos usar os componentes do *framework*. Use *framework* no estilo de bibliotecas. Dessa forma, permitimos que novos contribuidores adicionem valor do dia um, sem necessidade de mergulhar em detritos de complexidade relacionadas ao *framework* primeiro.\r\n\r\n> [Why I Hate Frameworks](https://minds.md/benji/frameworks)\r\n\r\n## Arquitetura em camadas\r\n\r\nHá uma certa emoção de engenharia em tudo isso.\r\n\r\nEu era um apaixonado advogado de arquitetura Hexagonal/Onion por anos. Usei e encorajei outros times a usar também. A complexidade de nossos projetos aumentaram, a quantidade de arquivos sozinhos dobraram. Parece como se eu estivesse escrevendo um monte de código-cola. A cada mudança de requerimento, temos de fazer mudanças entre múltiplas camadas de abstração, o que se torna tedioso. `🤯`\r\n\r\n**Abstrações são supostamente para ocultar complexidade, não adicionar [indireção](https://fhur.me/posts/2024/thats-not-an-abstraction)**. Pulando de chamada em chamada para ler e compreender o que há de errado e qual é o requerimento vital para rapidamente resolver o problema. Com essa arquitetura em camada, desacoplar requer um fator extra exponencial, frequentemente desarticulado, para chegar ao ponto onde a falha ocorre. Cada *stack trace* ocupa espaço em nossa limitada memória de trabalho. `🤯`\r\n\r\nEssa arquitetura foi algo que fez sentido intuitivo de primeira, mas cada vez que tentamos aplicá-la a projetos, isso fez mais mal que bem. Gastamos anos em atividade mental desnecessária e escrevemos código-cola inútil sem valor de negócios claro. Ao contrário, tornamos as coisas piores para os negócios ao forçar novatos a aprender nossas escolhas (modelos mentais) primeiro. O tempo de mercado tem piorado. E no final, desistimos em favor do bom e velho princípio de inversão de dependência. **Nenhum termo de porta ou adaptador para aprender, nenhuma camada horizontal de abstração, nenhuma carga coginitiva extrínseca**.\r\n\r\n\r\n Princípios de programação e experiência
\r\n
\r\n @flaviocopes\r\n \r\n\r\nSe você pensa que tal camadas irão te permitir rapidamente trocar o banco de dados ou quaisquer outras dependências, você está enganado. Mudar o armazenamento causa vários problemas, e acredite em nós, ter algumas abstrações para acessar a camada de dado é a última de suas preocupações. Ao menos, abstrações podem salvar algo entre 10% do nosso tempo de migração (se houver), a dor real está em incompatibilidades do modelo de dado, protocolo de comunicações, desafios de sistemas distrbuídos e [interfaces implícitas](https://www.hyrumslaw.com).\r\n\r\n> Com um número suficiente de usuários de uma API,\r\n> não importa qual a sua promessa no contrato:\r\n> todos os comportamentos de seu sistema\r\n> será dependente de alguém.\r\n\r\nFazemos uma migração de armazenamento, e levamos algo entre 10 meses. O sistema legado era *single-thread*, então os eventos expostos eram sequenciais. Todos os nossos sistemas dependem naquele comportamento observado. Esse comportamento não era parte de nosso contrato de API, e não refletia em nosso código. Um novo armazenamento distribuído não nos garantiu isso — os eventos chegam fora-de-ordem. Gastamos apenas algumas horas programando o novo adaptador do armazenamento, agradecimentos a uma abstração. **Gastamos os próximos 10 meses lidando com eventos fora-de-ordem e outros desafios**. Agora é engraçado dizer que abstrações nos ajudam a trocar componentes rapidamente.\r\n\r\n**Então, porque pagar o preço de carga cognitiva como uma arquitetura em camadas, se podemos não pagar no futuro?** Adicionalmente, na maioria dos casos, o futuro de trocar algum componente principal nunca acontece.\r\n\r\nEssas arquiteturas não são fundamentais, elas são apenas subjetivas, com consequências enviesadas de princípios mais fundamentais. Por que confiar nessas interpretações subjetivas? Siga regras fundamentais ao invés disso: princípio de invesão de dependência, única fonte de verdade, carga cognitiva e ocultação de informação. Nossa lógica de negócios não deveriam depender de módulos de baixo-nível, como banco de dados, interfaces de usuário ou *frameworks*. Deveriamos ser capazes de escrever testes para nossa lógica principal sem ter de nos perocupar com infraestrutura, e é isso. [Dicussão](https://github.com/zakirullin/cognitive-load/discussions/24)\r\n\r\nNão adicione camadas de abstração por conta da arquitetura. Adicione-as quando precisar de uma extensão a algum ponto como é justificável por razões práticas.\r\n\r\n**[Camadas de abstrações não são livres de mudanças](https://blog.jooq.org/why-you-should-not-implement-layered-architecture), elas são guardadas em nossa limitada memória de trabalho.**\r\n\r\n\r\n
\r\n
\r\n
\r\n
\r\n
\r\n
\r\n Comments
\r\n
\r\n Rob Pike (Unix, Golang)
Nice article.
\r\n Andrej Karpathy (ChatGPT, Tesla)
Nice post on software engineering. Probably the most true, least practiced viewpoint.
\r\n Elon Musk (Rockets)
True.
\r\n Addy Osmani (Chrome, the most complex software system in the world)
I've seen countless projects where smart developers created impressive architectures using the latest design patterns and microservices. But when new team members tried to make changes, they spent weeks just trying to understand how everything fits together. The cognitive load was so high that productivity plummeted and bugs multiplied.
\r\n The irony? Many of these complexity-inducing patterns were implemented in the name of \"clean code.\"
\r\n What really matters is reducing unnecessary cognitive burden. Sometimes this means fewer, deeper modules instead of many shallow ones. Sometimes it means keeping related logic together instead of splitting it into tiny functions.
\r\n And sometimes it means choosing boring, straightforward solutions over clever ones. The best code isn't the most elegant or sophisticated - it's the code that future developers (including yourself) can understand quickly.
\r\n Your article really resonates with the challenges we face in browser development. You're absolutely right about modern browsers being among the most complex software systems. Managing that complexity in Chromium is a constant challenge that aligns perfectly with many of the points you made about cognitive load.
\r\n One way we try to handle this in Chromium is through careful component isolation and well-defined interfaces between subsystems (like rendering, networking, JavaScript execution, etc.). Similar to your deep modules example with Unix I/O - we aim for powerful functionality behind relatively simple interfaces. For instance, our rendering pipeline handles incredible complexity (layout, compositing, GPU acceleration) but developers can interact with it through clear abstraction layers.
\r\n Your points about avoiding unnecessary abstractions really hit home too. In browser development, we constantly balance between making the codebase approachable for new contributors while handling the inherent complexity of web standards and compatibility.
\r\n Sometimes the simplest solution is the best one, even in a complex system.
\r\n antirez (Redis)
Totally agree about it :) Also, what I believe is missing from mentioned \"A Philosophy of Software Design\" is the concept of \"design sacrifice\". That is, sometimes you sacrifice something and get back simplicity, or performances, or both. I apply this idea continuously, but often is not understood.
\r\n A good example is the fact that I always refused to have hash items expires. This is a design sacrifice because if you have certain attributes only in the top-level items (the keys themselves), the design is simpler, values will just be objects. When Redis got hash expires, it was a nice feature but required (indeed) many changes to many parts, raising the complexity.
\r\n Another example is what I'm doing right now, Vector Sets, the new Redis data type. I decided that Redis would not be the source of truth about vectors, but that it can just take an approximate version of them, so I was able to do on-insert normalization, quantization without trying to retain the large floats vector on disk, and so forth. May vector DBs don't sacrifice the fact of remembering what the user put inside (the full precision vector).
\r\n These are just two random examples, but I apply this idea everywhere. Now the thing is: of course one must sacrifice the right things. Often, there are 5% features that account for a very large amount of complexity: that is a good thing to kill :D
\r\n A developer from the internet
You would not hire me... I sell myself on my track record of released enterprise projects.
\r\n I worked with a guy that could speak design patterns. I could never speak that way, though I was one of the few that could well understand him. The managers loved him and he could dominate any development conversation. The people working around him said he left a trail of destruction behind him. I was told that I was the first person that could understand his projects. Maintainability matters. I care most about TCO. For some firms, that's what matters.
\r\n I logged into Github after not being there for a while and for some reason it took me to an article in a repository by someone that seemed random. I was thinking \"what is this\" and had some trouble getting to my home page, so I read it. I didn't really register it at the time, but it was amazing. Every developer should read it. It largely said that almost everything we've been told about programming best practices leads to excessive \"cognitive load\", meaning our minds are getting kicked by the intellectual demands. I've known this for a while, especially with the demands of cloud, security and DevOps.
\r\n I also liked it because it described practices I have done for decades, but never much admit to because they are not popular... I write really complicated stuff and need all the help I can get.
\r\n Consider, if I'm right, it popped up because the Github folks, very smart people, though that developers should see it. I agree.
\r\n Comments on Hacker News (2)
\r\n \r\n"
},
{
"path": "README.tr.md",
"content": "# Önemli olan bilişsel yüktür\n\n## Giriş\n\nEtrafta hatrı sayılır sayıda klişe söylemler ve \"best practice\" yapılar var, fakat bunların çoğu sadece sözde kalmış ve başarısızlıkla sonuçlanmıştır. Bizimse daha temel bir şeye ihtiyacımız var — yanlış olamayacak bir şeye.\n\nBazen bir kodu okurken kafa karışıklığı yaşarız. Bu karışıklık bize zaman ve para kaybettirir. Bunun nedeni, yüksek **bilişsel yüktür**.\n\nBu, öyle süslü püslü ve soyut bir kavram değil; aksine, **insan zihninin doğasından gelen temel bir sınırlamadır**. Hayal ürünü değil — gerçekten orada ve hepimiz onu hissediyoruz.\n\nÇünkü kod yazmaya harcadığımız zamandan çok daha fazlasını onu **okumaya** ve **anlamaya** harcıyoruz. Bu yüzden kendimize sürekli şu soruyu sormalıyız: \n\"**Yazdığımız koda gereğinden fazla bilişsel yük yüklüyor muyuz?**\" \n\n## Bilişsel yük\n\n> Bilişsel yük, bir geliştiricinin bir görevi tamamlamak için ne kadar düşünmesi gerektiğidir.\n\nKod okurken; değişken değerlerini, kontrol akışını ve fonksiyon çağrı dizilerini zihnimizde tutmamız gerekir. Fakat ilginçtir ki, ortalama bir insan, çalışma belleğinde bu türden yalnızca yaklaşık **[dört bilgi parçasını](https://github.com/zakirullin/cognitive-load/issues/16)** tutabilir. Bilişsel yük bu eşiğe ulaştığında, kodu anlamak **ciddi şekilde zorlaşır**.\n\n*Diyelim ki bize tamamen yabancı bir projede bazı hataları düzeltmemiz söylendi. Projeye daha önce çok zeki bir geliştirici katkıda bulunmuş. \nKulağa harika geliyor: karmaşık mimariler, havalı kütüphaneler ve trend teknolojiler kullanılmış. \nYani başka bir deyişle, **yazarı bizim için oldukça yüksek bir bilişsel yük üretmiş**.*\n\n\n
![\"Cognitive](\"img/cognitiveloadv6.png\")
\n
\n Bilişsel yük ve bölünmeler
\n
\n \n\n## Bilişsel yükün türleri\n\n**İçsel yük** - Görevin kendi doğasından gelen zorluk. Bu yük azaltılamaz; çünkü yazılım geliştirmenin tam kalbinde yer alır.\n\n**Dışsal yük** - Bilginin sunuluş biçiminden kaynaklanır. Görevle doğrudan ilgisi olmayan ama kafa karıştıran unsurlar yüzünden oluşur — mesela “çok zeki” yazarın kendine has tuhaflıkları gibi. Bu tür yük ciddi şekilde azaltılabilir. Biz de zaten bu tip düşünsel yükü azaltmaya odaklanacağız. \n\n\n
![\"Intrinsic](\"img/smartauthorv14thanksmari.png\")
\n
\n
![\"Deep](\"img/deepmodulev8.png\")
\n
\n 20 yıllık C++ deneyimine sahip bir mühendisin düşünceleri ⭐️
\n
\n Geçen gün RSS okuyucuma baktım, “C++” etiketi altında yaklaşık üç yüz okunmamış makalem olduğunu gördüm. Geçen yazdan beri C++ ile ilgili tek bir makale okumamışım ve buna rağmen harika hissediyorum!
\n 20 yıldır C++ kullanıyorum, hayatımın neredeyse üçte ikisi bu dilde geçti. Deneyimimin çoğu dilin en karmaşık ve karanlık köşeleriyle ilgili (mesela her türlü tanımsız davranışlar). Bu deneyim kolayca başkalarına aktarılamaz ve şimdi bunu bir kenara bırakmak biraz ürkütücü.
\n Mesela, || operatörünün requires ((!P || !Q)) ile requires (!(P || Q)) arasında tamamen farklı anlamları var. İlki kısıtlar arası “veya” anlamındayken, ikincisi klasik mantıksal OR operatörü ve davranışları da farklı.
\n Önceki C++ sürümlerinde trivial (basit) tipler için ayrılan belleğe sadece memcpy yaparak nesne yaşam döngüsünü başlatamazdınız. Bu, C++20 ile düzeltildi ama dilin bilişsel yükü yine de arttı.
\n Bilişsel yük hep artıyor; düzeltmeler yapılsa da, neyin ne zaman düzeltildiğini, öncesini bilmek zorundayım. Sonuçta profesyonelim. C++’un güçlü olduğu miras desteği, demek ki bu eski karmaşıklıklarla karşılaşmaya devam edeceksiniz. Mesela geçen ay bir meslektaşım C++03’teki bir davranışı sordu. 🤯
\n Initialization'ın 20 farklı yolu vardı, *Uniform initialization syntax* geldi ve 21 yol oldu. Ayrıca, initializer list’ten constructorların seçilmesi için kuralları hatırlayan var mı? En az bilgi kaybıyla implicit conversion... Ama eğer değer statik olarak biliniyorsa... 🤯
\n Bu artan bilişsel yük, yaptığımız işten kaynaklanmıyor. Alanın doğal bir karmaşıklığı da değil. Tarihten gelen, gereksiz bir yük (extraneous cognitive load).
\n Kendime bazı kurallar koydum: Eğer bir kod satırı çok karmaşıksa ve standartları hatırlamam gerekiyorsa, o şekilde yazmamaya çalışıyorum. Standardın kendisi de yaklaşık 1500 sayfa.
\n C++’ı suçlamıyorum, dili çok seviyorum. Ama artık yoruldum.
\n Bu yazı için 0xd34df00d'a teşekkür ederim.
\n \n\n## Business logic ve HTTP durum kodları\n\nBackend tarafında şu değerleri döndürüyoruz: \n`401` JWT tokeninin süresi dolduğunda \n`403` yeterli erişim izni olmadığında \n`418` kullanıcı banlanmış olduğunda \n\nFrontend mühendisleri, login işlevini gerçekleştirmek için backend API’sini kullanıyorlar. Bu sırada beyinlerinde geçici olarak şu bilişsel yükü oluşturmak zorunda kalıyorlar: \n`401` JWT tokeninin süresi dolduğunda // `🧠+`, sadece geçici olarak bunu aklında tutmam gerek \n`403` yeterli erişim izni olmadığında // `🧠++` \n`418` kullanıcı banlanmış olduğunda // `🧠+++` \n\nFrontend geliştiricileri, (umarız ki) kendi taraflarında bir `sayısal durum kodu → anlamı` **sözlüğü** oluştururlar. Böylece sonraki katkıda bulunanlar, bu eşlemeyi tekrar kendi kafalarında kurmak zorunda kalmazlar.\n\nSonra devreye QA (Kalite Güvence) mühendisleri girer:\n\"Hey, bana `403` durumu geldi, bu süresi dolmuş token mı yoksa yetersiz erişim mi?\" \n**QA mühendisleri doğrudan teste geçemez, önce backend mühendislerinin oluşturduğu bilişsel yükü kendi kafalarında yeniden yaratmak zorundadırlar.**\"\n\nNeden bu özel eşlemeyi sürekli çalışma hafızamızda tutalım ki? İş detaylarını HTTP transfer protokolünden soyutlamak ve cevap gövdesinde kendini açıklayan kodlar döndürmek çok daha iyidir:\n\n```json\n{\n \"code\": \"jwt_has_expired\"\n}\n```\n\nFrontend tarafındaki bilişsel yük: `🧠` (yeni, akılda tutulacak bilgi yok) \nQA tarafındaki bilişsel yük: `🧠`\n\nAynı kural her türlü sayısal durum için geçerlidir (veritabanında ya da başka bir yerde) — **kendini açıklayan metinleri tercih edin**. Artık hafızayı optimize etmek için 640K bilgisayarların çağı değiliz. \n\n> İnsanlar `401` ile `403` arasında tartışmakla zaman harcıyor, kendi zihinsel modellerine göre karar veriyorlar. Yeni geliştiriciler geliyor ve o düşünce sürecini tekrar yaratmak zorunda kalıyorlar. Kodunuz için “neden”leri (ADRs) belgelemiş olabilirsiniz; bu, yeni gelenlerin alınan kararları anlamasına yardımcı olur. Ama sonuçta bu çok da mantıklı değil. Hataları ya kullanıcı kaynaklı ya da sunucu kaynaklı olarak ayırabiliriz; onun dışında kalanlar ise biraz muğlak kalıyor. \n\nNot: “Kimlik doğrulama” (authentication) ile “yetkilendirme” (authorization) arasındaki farkı ayırt etmek genellikle zihinsel olarak yorucudur. Bilişsel yükü azaltmak için [\"giriş\" (login) ve \"izinler\" (permissions)](https://ntietz.com/blog/lets-say-instead-of-auth/) gibi daha basit terimler kullanabiliriz.\n\n## DRY prensibini yanlış kullanmak\n\n**Kendini Tekrar Etme (Don’t Repeat Yourself - DRY)** prensibi, yazılım mühendisi olarak öğretilen ilk ve temel prensiplerden biridir. Bu prensip o kadar içimize işlemiştir ki, fazladan birkaç satır kod görmek bile tahammül edilemez gelir. Genel olarak iyi ve temel bir kural olsa da, aşırı kullanıldığında başa çıkamayacağımız bilişsel yüke yol açabilir.\n\nGünümüzde herkes, mantıksal olarak ayrılmış bileşenler üzerine yazılım geliştiriyor. Bu bileşenler çoğunlukla, ayrı hizmetleri temsil eden birden fazla kod tabanına dağıtılmış durumda oluyor. Tekrarı tamamen ortadan kaldırmaya çalışırken, alakasız bileşenler arasında sıkı bir bağlılık (tight coupling) yaratma riski ortaya çıkar. Bunun sonucu olarak, bir bölümde yapılan değişiklikler, görünüşte alakasız diğer bölümlerde beklenmedik etkiler yaratabilir. Ayrıca, bu durum bireysel bileşenleri değiştirmeyi veya yenilemeyi zorlaştırır çünkü sistemin tamamını etkileyebilir. `🤯` \n\nAslında aynı sorun tek bir modül içinde de ortaya çıkabilirdi. Ortak işlevselliği, uzun vadede gerçekten var olmayan benzerliklere dayanarak çok erken bir aşamada soyutlamaya çalışabilirsiniz. Bu da gereksiz soyutlamalar oluşturur ve bunlar üzerinde değişiklik yapmak ya da genişletmek zorlaşır. \n\nRob Pike bir keresinde şöyle demiştir:\n\n> Biraz kopyalamak, biraz bağımlı olmaktan daha iyidir. \n\nTekerleği yeniden icat etmemek adına öyle güçlü bir şekilde eğilimliyiz ki, kendi başımıza kolayca yazabileceğimiz küçük bir fonksiyonu kullanmak için büyük ve ağır kütüphaneleri içe aktarmaya hazırız. \n\n**Ama aslında tüm bağımlılıklarınız sizin kodunuzdur.** Dışarıdan alınan bir kütüphanenin 10’dan fazla katmanlı stack trace’ini inceleyip neyin yanlış gittiğini anlamaya çalışmak (*çünkü hatalar olur*) gerçekten zor ve yorucu bir süreçtir. \n\n## Bir framework ile sıkı bağlılık (tight coupling)\n\nFramework’lerde bolca “sihir” vardır. Bir framework’e çok fazla bağlı kaldığımızda, **gelecek tüm geliştiricilerin önce o “sihiri” öğrenmesini zorunlu kılmış oluruz.** Bu da aylar sürebilir. Framework’ler, MVP’leri birkaç gün içinde hayata geçirmemizi sağlasa da, uzun vadede gereksiz karmaşıklık ve bilişsel yük eklemeye meyillidirler.\n\nDahası, bir noktada framework’ler, mimariye uymayan yeni bir gereksinimle karşılaşıldığında ciddi bir kısıtlayıcı haline gelebilir. Bu noktadan sonra insanlar framework’ü çatallayıp (fork) kendi özel versiyonlarını yönetmek zorunda kalırlar. Yeni gelen birinin, herhangi bir değer katabilmek için bu özel framework’ü öğrenerek üstlenmesi gereken bilişsel yükü bir düşünün. `🤯`\n\n**Kesinlikle her şeyi baştan icat etmeyi savunmuyoruz!**\n\nKodu mümkün olduğunca framework'ten bağımsız yazabiliriz. İş mantığı framework’ün içinde yer almamalı, onun yerine framework bileşenlerini kullanmalı. Framework’ü çekirdek mantığınızın dışına koyun. Framework’ü bir kütüphane gibi kullanın. Böylece yeni katılımcılar, framework kaynaklı karmaşanın içinde kaybolmadan, ilk günden itibaren projeye değer katabilirler. \n\n> [Frameworklerden neden nefret ediyorum](https://minds.md/benji/frameworks)\n\n## Katmanlı mimari\n\nBütün bunlarda belli bir mühendislik heyecanı var.\n\nBen de yıllarca Hexagonal/Onion Mimarisi’nin tutkulu bir savunucusu oldum. Bunu çeşitli projelerde kullandım ve diğer ekipleri de teşvik ettim. Ancak projelerimizin karmaşıklığı arttı, sadece dosya sayısı bile iki katına çıktı. Sanki çok fazla “glue code” yazıyormuşuz gibi hissettik. Sürekli değişen gereksinimler karşısında, birden fazla soyutlama katmanında değişiklik yapmak zorunda kalmak çok yorucu hale geldi. `🤯`\n\nSoyutlama (abstraction) aslında karmaşıklığı gizlemek için vardır; ancak burada sadece [dolaylılık (indirection)](https://fhur.me/posts/2024/thats-not-an-abstraction) ekliyor. Sorunu hızlıca çözmek için çağrılar arasında zıplayarak (jumping from call to call) neyin yanlış gittiğini ve neyin eksik olduğunu anlamak hayati bir gerekliliktir. Bu mimaride katmanlar arasındaki gevşek bağlantı (layer uncoupling) sebebiyle, hatanın meydana geldiği noktaya ulaşmak için çok daha fazla ve çoğu zaman birbirinden kopuk (disjointed) iz sürme işlemi (trace) gerekir. Her böyle iz sürme, sınırlı olan çalışma belleğimizde (working memory) yer kaplar ve bilişsel yükü (cognitive load) artırır. `🤯` \n\nBu mimari başlangıçta sezgisel (intuitive) olarak mantıklı görünüyordu; ancak projelere uygulamaya çalıştıkça faydasından çok zarar verdiğini gördük. Sonunda tüm bu karmaşıklığı bırakıp klasik **dependency inversion principle** (bağımlılıkların tersine çevrilmesi ilkesi) lehine vazgeçtik. Artık **port/adapter gibi karmaşık terimler öğrenmeye gerek yok, gereksiz yatay soyutlama katmanları yok, ve fazladan bilişsel yük (cognitive load) yok**. Bu sayede kod daha sade, anlaşılır ve yönetilebilir hale geldi.\n\n\n Kodlama prensipleri ve deneyim eğrisi
\n
\n @flaviocopes\n \n\nEğer böyle bir katmanlandırmanın (layering) veritabanını veya diğer bağımlılıkları hızlıca değiştirmenize olanak sağlayacağını düşünüyorsanız, yanılıyorsunuz. Depolama katmanını değiştirmek birçok problem yaratır ve inanın, veri erişim katmanı için bazı soyutlamalara (abstraction) sahip olmak endişelerinizin en küçüğüdür. En iyi ihtimalle, soyutlamalar geçiş sürenizin yaklaşık %10’unu (eğer varsa) kurtarabilir; asıl zorluk veri modeli uyumsuzluklarında, iletişim protokollerinde, dağıtık sistemlerin getirdiği karmaşıklıklarda ve [örtük arayüzlerde (implicit interfaces)](https://www.hyrumslaw.com) yatar. \n\n> Yeterli sayıda API kullanıcınız olduğunda, \n> sözleşmede ne vaat ettiğiniz önemli değildir: \n> sisteminizin tüm gözlemlenebilir davranışlarına \n> birileri bağımlı olacaktır.\n\nBir depolama geçişi yaptık ve bu yaklaşık 10 ay sürdü. Eski sistem tek iş parçacıklıydı, dolayısıyla ortaya çıkan olaylar sıralıydı. Tüm sistemlerimiz bu gözlemlenen davranışa bağımlıydı. Bu davranış API sözleşmesinin bir parçası değildi, koda yansıtılmamıştı. Yeni dağıtık depolama bu garantiyi vermiyordu — olaylar sırasız (out-of-order) geliyordu. Yeni bir depolama adaptörü yazmak sadece birkaç saatimizi aldı, soyutlama sayesinde. **Ancak sonraki 10 ayı sırasız olaylar ve diğer zorluklarla uğraşarak geçirdik.** Artık soyutlamaların bileşenleri hızlıca değiştirmemize yardımcı olduğu söylemesi komik oluyor. \n\n**Peki, böyle katmanlı bir mimarinin yüksek bilişsel yükünün bedelini neden ödeyelim ki, eğer bu ileride karşılığını vermiyorsa?** Üstelik çoğu durumda, o temel bileşeni değiştirme geleceği hiç gerçekleşmez. \n\nBu mimariler temel değildir; onlar sadece daha temel prensiplerin öznel, yanlı yorumlarıdır. Neden bu öznel yorumlara dayanırsınız? Bunun yerine temel kuralları takip edin: Bağımlılıkları tersine çevirme prensibi (dependency inversion principle), tek gerçek kaynağı (single source of truth), bilişsel yük (cognitive load) ve bilgi gizleme (information hiding). İş mantığınız, veritabanı, kullanıcı arayüzü veya framework gibi düşük seviyeli modüllere bağlı olmamalıdır. Altyapıyı düşünmeden çekirdek mantığımız için testler yazabilmeliyiz, hepsi bu. [Tartışıma](https://github.com/zakirullin/cognitive-load/discussions/24).\"\n\nMimari adına katmanlar veya soyutlamalar eklemeyin. Sadece gerektiğinde pratik nedenlerle gerekçelendirilmiş bir genişletme noktası (extension point) ekleyin.\n\n[Soyutlama katmanları ücretsiz değildir](https://blog.jooq.org/why-you-should-not-implement-layered-architecture); bunlar sınırlı olan çalışma belleğimizde (working memory) tutulmak zorundadır.\n\n\n
![\"Layers\"](\"img/layers.png\")
\n
\n
![\"Mental](\"img/mentalmodelsv15.png\")
\n
\n
\n
\n Yorumlar
\n
\n Rob Pike
Nice article.
\n Andrej Karpathy (ChatGPT, Tesla)
Nice post on software engineering. Probably the most true, least practiced viewpoint.
\n Elon Musk
True.
\n Addy Osmani (Chrome, the most complex software system in the world)
I've seen countless projects where smart developers created impressive architectures using the latest design patterns and microservices. But when new team members tried to make changes, they spent weeks just trying to understand how everything fits together. The cognitive load was so high that productivity plummeted and bugs multiplied.
\n The irony? Many of these complexity-inducing patterns were implemented in the name of \"clean code.\"
\n What really matters is reducing unnecessary cognitive burden. Sometimes this means fewer, deeper modules instead of many shallow ones. Sometimes it means keeping related logic together instead of splitting it into tiny functions.
\n And sometimes it means choosing boring, straightforward solutions over clever ones. The best code isn't the most elegant or sophisticated - it's the code that future developers (including yourself) can understand quickly.
\n Your article really resonates with the challenges we face in browser development. You're absolutely right about modern browsers being among the most complex software systems. Managing that complexity in Chromium is a constant challenge that aligns perfectly with many of the points you made about cognitive load.
\n One way we try to handle this in Chromium is through careful component isolation and well-defined interfaces between subsystems (like rendering, networking, JavaScript execution, etc.). Similar to your deep modules example with Unix I/O - we aim for powerful functionality behind relatively simple interfaces. For instance, our rendering pipeline handles incredible complexity (layout, compositing, GPU acceleration) but developers can interact with it through clear abstraction layers.
\n Your points about avoiding unnecessary abstractions really hit home too. In browser development, we constantly balance between making the codebase approachable for new contributors while handling the inherent complexity of web standards and compatibility.
\n Sometimes the simplest solution is the best one, even in a complex system.
\n antirez (Redis)
Totally agree about it :) Also, what I believe is missing from mentioned \"A Philosophy of Software Design\" is the concept of \"design sacrifice\". That is, sometimes you sacrifice something and get back simplicity, or performances, or both. I apply this idea continuously, but often is not understood.
\n A good example is the fact that I always refused to have hash items expires. This is a design sacrifice because if you have certain attributes only in the top-level items (the keys themselves), the design is simpler, values will just be objects. When Redis got hash expires, it was a nice feature but required (indeed) many changes to many parts, raising the complexity.
\n Another example is what I'm doing right now, Vector Sets, the new Redis data type. I decided that Redis would not be the source of truth about vectors, but that it can just take an approximate version of them, so I was able to do on-insert normalization, quantization without trying to retain the large floats vector on disk, and so forth. May vector DBs don't sacrifice the fact of remembering what the user put inside (the full precision vector).
\n These are just two random examples, but I apply this idea everywhere. Now the thing is: of course one must sacrifice the right things. Often, there are 5% features that account for a very large amount of complexity: that is a good thing to kill :D
\n \n"
},
{
"path": "README.vi.md",
"content": "# Cognitive load mới là thứ quan trọng\n\n[Prompt](https://github.com/zakirullin/cognitive-load/blob/main/README.prompt.md) | [Blog version](https://minds.md/zakirullin/cognitive) | [Chinese](https://github.com/zakirullin/cognitive-load/blob/main/README.zh-cn.md) | [Korean](README.ko.md) | [Turkish](README.tr.md) | [Japanese](README.ja.md) | [Vietnamese](README.vi.md)\n\n*Đây là tài liệu sống, cập nhật lần cuối: **Tháng 10/2025.** Mọi đóng góp đều được chào đón!*\n\n## Giới thiệu\nCó quá nhiều buzzword và best practice ngoài kia, nhưng phần lớn đều thất bại. Chúng thất bại vì chúng được tưởng tượng ra, không phải thực tế. Những ý tưởng này dựa trên thẩm mỹ và đánh giá chủ quan. Chúng ta cần thứ gì đó fundamental hơn, thứ không thể sai được.\n\nĐôi khi chúng ta cảm thấy bối rối khi đọc code. Sự bối rối tốn thời gian và tiền bạc. Sự bối rối được gây ra bởi *cognitive load* cao. Đây không phải một khái niệm trừu tượng fancy, mà là **một giới hạn cơ bản của con người.** Nó không phải tưởng tượng, nó ở đó và chúng ta cảm nhận được.\n\nVì chúng ta dành nhiều thời gian đọc và hiểu code hơn là viết nó, chúng ta nên liên tục tự hỏi liệu mình có đang nhét quá nhiều cognitive load vào code hay không.\n\n## Cognitive load\n> Cognitive load là lượng suy nghĩ mà một developer cần để hoàn thành một task.\n\nKhi đọc code, bạn đưa các thứ như giá trị biến, control flow logic và call sequence vào đầu. Một người bình thường có thể giữ khoảng [bốn chunk như vậy](https://github.com/zakirullin/cognitive-load/issues/16) trong working memory. Khi cognitive load đạt ngưỡng này, việc hiểu trở nên khó khăn hơn nhiều.\n\n*Giả sử chúng ta được yêu cầu fix bug cho một project hoàn toàn xa lạ. Người ta nói có một developer thông minh đã contribute vào đó. Nhiều kiến trúc xịn, library fancy và công nghệ trendy được sử dụng. Nói cách khác, **tác giả đã tạo ra cognitive load cao cho chúng ta.***\n\n\n
\n
\n Cognitive load và interruption
\n \n
\n
\n\n> Chúng ta sẽ dùng \"cognitive load\" theo nghĩa informal; đôi khi nó khớp với khái niệm khoa học về Cognitive Load, nhưng chúng ta không biết chính xác chỗ nào khớp và chỗ nào không.\n\n## Các loại cognitive load\n**Intrinsic** - do độ khó vốn có của task gây ra. Không thể giảm được, nó nằm trong bản chất của software development.\n\n**Extraneous** - do cách trình bày thông tin tạo ra. Do các yếu tố không liên quan trực tiếp đến task, như thói quen của tác giả thông minh. Có thể giảm đáng kể. Chúng ta sẽ tập trung vào loại cognitive load này.\n\n\n
\n
\n
\n
\n Những thứ quan trọng nên to, ví dụ
\n
\n \n
\n
Nếu bạn cho phép các function \"crux\" quan trọng to hơn (\"dirty\"), sẽ dễ dàng hơn để pick chúng ra khỏi biển function, chúng rõ ràng là quan trọng: nhìn vào chúng, chúng to!
\n Hình này được lấy từ bài Codin' Dirty của Carson Gross. Bạn sẽ tìm thấy ví dụ thực tế về deep function ở đó.\n \n\nP.S. Nếu bạn nghĩ chúng ta đang ủng hộ God object phình to với quá nhiều responsibility, bạn hiểu sai rồi.\n\n## Responsible cho một thing\nQuá thường xuyên, chúng ta tạo ra nhiều shallow module, theo một nguyên tắc mơ hồ \"một module nên responsible cho một, và chỉ một, thing\". Cái \"một thing\" mơ hồ này là gì? Khởi tạo một object là một thing, đúng không? Vậy [MetricsProviderFactoryFactory](https://minds.md/benji/frameworks) có vẻ ổn. **Tên và interface của các class như vậy có xu hướng tốn não hơn toàn bộ implementation của chúng, đó là abstraction kiểu gì?** Có gì đó sai sai.\n\nChúng ta thay đổi hệ thống để thỏa mãn user và stakeholder. Chúng ta responsible với họ.\n\n> Một module nên responsible với một, và chỉ một, user hoặc stakeholder.\n\nĐây là bản chất của Single Responsibility Principle. Nói đơn giản, nếu ta gây ra bug ở một chỗ, rồi hai business people khác nhau đến phàn nàn, ta đã vi phạm nguyên tắc. Nó không liên quan gì đến số lượng thing ta làm trong module.\n\nNhưng ngay cả bây giờ, rule này có thể gây hại nhiều hơn lợi. Nguyên tắc này có thể được hiểu theo nhiều cách khác nhau tùy mỗi người. Approach tốt hơn là nhìn vào lượng cognitive load mà nó tạo ra. Rất tốn não để nhớ rằng thay đổi ở một chỗ có thể trigger chuỗi phản ứng qua các business stream khác nhau. Và chỉ vậy thôi, không cần học fancy term gì cả.\n\n## Quá nhiều shallow microservice\nNguyên tắc shallow-deep module này scale-agnostic, và ta có thể áp dụng nó cho microservices architecture. Quá nhiều shallow microservice không tốt - ngành đang hướng tới \"macroservice\", tức là service không quá shallow (=deep). Một trong những hiện tượng tệ nhất và khó fix nhất là distributed monolith, thường là kết quả của việc phân tách shallow quá mức này.\n\nTôi từng tư vấn cho một startup nơi team năm developer tạo ra 17(!) microservice. Họ chậm 10 tháng so với lịch trình và không gần tới public release. Mỗi requirement mới dẫn đến thay đổi trong 4+ microservice. Mất vô cùng nhiều thời gian để reproduce và debug issue trong distributed system như vậy. Cả time to market và cognitive load đều cao không thể chấp nhận. `🤯`\n\nĐây có phải cách đúng để tiếp cận uncertainty của hệ thống mới? Cực kỳ khó để xác định đúng logical boundary ngay từ đầu. Điều quan trọng là đưa ra quyết định càng muộn càng tốt, vì lúc đó bạn có nhiều thông tin nhất. Bằng cách đưa network layer vào ngay từ đầu, ta làm cho design decision khó revert ngay từ lúc bắt đầu. Lý do duy nhất của team là: \"Các công ty FAANG đã chứng minh microservices architecture hiệu quả\". *Hello, bạn phải thôi mơ lớn đi.*\n\n[Tranh luận Tanenbaum-Torvalds](https://en.wikipedia.org/wiki/Tanenbaum%E2%80%93Torvalds_debate) cho rằng thiết kế monolithic của Linux là lỗi thời và nên dùng microkernel architecture thay thế. Thật vậy, thiết kế microkernel có vẻ vượt trội \"từ góc độ lý thuyết và thẩm mỹ\". Về mặt thực tế - ba thập kỷ sau, GNU Hurd dựa trên microkernel vẫn đang phát triển, còn monolithic Linux thì ở khắp nơi. Trang này chạy bằng Linux, ấm đun nước thông minh của bạn cũng chạy Linux. Bằng monolithic Linux.\n\nMột monolith được craft tốt với các module thật sự isolated thường linh hoạt hơn nhiều so với một đống microservice. Nó cũng cần ít cognitive effort hơn nhiều để maintain. Chỉ khi nhu cầu deploy riêng biệt trở nên quan trọng, như scale development team, bạn mới nên xem xét thêm network layer giữa các module, các microservice tương lai.\n\n## Ngôn ngữ feature-rich\nChúng ta hào hứng khi các feature mới được release trong ngôn ngữ yêu thích. Chúng ta dành thời gian học các feature này, build code dựa trên chúng.\n\nNếu có nhiều feature, ta có thể tốn nửa giờ chơi với vài dòng code, để dùng feature này hay feature kia. Và đó hơi lãng phí thời gian. Nhưng tệ hơn, **khi bạn quay lại sau, bạn phải recreate lại thought process đó!**\n\n**Bạn không chỉ phải hiểu chương trình phức tạp này, bạn còn phải hiểu tại sao một programmer quyết định đây là cách tiếp cận vấn đề từ các feature có sẵn.** `🤯`\n\nNhững phát biểu này được đưa ra bởi không ai khác ngoài Rob Pike.\n\n> Giảm cognitive load bằng cách giới hạn số lượng choice.\n\nLanguage feature là OK, miễn là chúng orthogonal với nhau.\n\n\n Suy nghĩ từ một engineer với 20 năm kinh nghiệm C++ ⭐️
\n
\n Hôm trước tôi nhìn RSS reader và nhận ra có khoảng ba trăm bài chưa đọc dưới tag \"C++\". Tôi chưa đọc một bài nào về ngôn ngữ này từ mùa hè năm ngoái, và tôi cảm thấy tuyệt!
\n Tôi đã dùng C++ được 20 năm rồi, gần hai phần ba cuộc đời tôi. Phần lớn kinh nghiệm của tôi là deal với những góc tối nhất của ngôn ngữ (như undefined behaviour đủ loại). Đây không phải kinh nghiệm tái sử dụng được, và hơi đáng sợ khi phải bỏ hết bây giờ.
\n Kiểu như, bạn có thể tưởng tượng được không, token || có nghĩa khác nhau trong requires ((!P<T> || !Q<T>)) và trong requires (!(P<T> || Q<T>)). Cái đầu là constraint disjunction, cái thứ hai là operator logical OR quen thuộc, và chúng hoạt động khác nhau.
\n Bạn không thể allocate space cho trivial type và chỉ memcpy một set byte vào đó mà không cần thêm effort - điều đó sẽ không bắt đầu lifetime của một object. Đây là tình huống trước C++20. Nó đã được fix trong C++20, nhưng cognitive load của ngôn ngữ chỉ tăng lên.
\n Cognitive load liên tục tăng, dù mọi thứ được fix. Tôi phải biết cái gì được fix, khi nào nó được fix, và trước đó nó như thế nào. Tôi là một professional mà. Chắc chắn, C++ giỏi về legacy support, điều đó cũng có nghĩa là bạn sẽ gặp legacy đó. Ví dụ, tháng trước một đồng nghiệp hỏi tôi về một behaviour trong C++03. 🤯
\n Có 20 cách initialization. Uniform initialization syntax được thêm vào. Bây giờ có 21 cách initialization. Nhân tiện, có ai nhớ rule để chọn constructor từ initializer list không? Một cái gì đó về implicit conversion với ít loss thông tin nhất, nhưng nếu giá trị được biết statically thì... 🤯
\n Cognitive load tăng lên này không phải do business task đang làm. Không phải intrinsic complexity của domain. Nó chỉ ở đó do lý do lịch sử (extraneous cognitive load).
\n Tôi phải nghĩ ra vài rule. Kiểu như, nếu dòng code đó không rõ ràng và tôi phải nhớ standard, tốt hơn là không viết kiểu đó. Standard dài khoảng 1500 trang, nhân tiện.
\n Tôi hoàn toàn không blame C++. Tôi yêu ngôn ngữ này. Chỉ là tôi mệt rồi.
\n Cảm ơn 0xd34df00d đã viết.
\n \n\n## Business logic và HTTP status code\nỞ backend ta return:\n`401` cho expired JWT token\n`403` cho không đủ access\n`418` cho banned user\n\nCác engineer ở frontend dùng backend API để implement login functionality. Họ sẽ phải tạm thời tạo cognitive load sau trong đầu:\n`401` là cho expired JWT token // `🧠+`, ok chỉ nhớ tạm thời\n`403` là cho không đủ access // `🧠++`\n`418` là cho banned user // `🧠+++`\n\nFrontend developer sẽ (hy vọng) tạo một loại dictionary `numeric status -> meaning` ở phía họ, để các contributor thế hệ sau không phải recreate mapping này trong đầu.\n\nRồi QA engineer vào cuộc:\n\"Hey, tôi nhận được status `403`, đó là expired token hay không đủ access?\"\n**QA engineer không thể nhảy thẳng vào testing, vì trước tiên họ phải recreate cognitive load mà engineer backend đã tạo.**\n\nTại sao phải giữ custom mapping này trong working memory? Tốt hơn là abstract business detail ra khỏi HTTP transfer protocol, và return code tự mô tả trực tiếp trong response body:\n```json\n{\n \"code\": \"jwt_has_expired\"\n}\n```\n\nCognitive load ở phía frontend: `🧠` (fresh, không có fact nào được giữ trong đầu)\nCognitive load ở phía QA: `🧠`\n\nRule tương tự áp dụng cho tất cả loại numeric status (trong database hay bất kỳ đâu) - **ưu tiên string tự mô tả.** Chúng ta không còn ở thời đại máy 640K để optimize memory nữa.\n\n> Mọi người dành thời gian tranh luận giữa `401` và `403`, đưa ra quyết định dựa trên mental model riêng của họ. Developer mới vào phải recreate thought process đó. Bạn có thể đã document \"why\" (ADR) cho code, giúp newcomer hiểu quyết định đã đưa ra. Nhưng cuối cùng nó chẳng có ý nghĩa gì. Ta có thể tách error thành user-related hoặc server-related, nhưng ngoài ra thì mọi thứ hơi mơ hồ.\n\nP.S. Thường rất tốn não để phân biệt giữa \"authentication\" và \"authorization\". Ta có thể dùng term đơn giản hơn như [\"login\" và \"permission\"](https://ntietz.com/blog/lets-say-instead-of-auth/) để giảm cognitive load.\n\n## Lạm dụng nguyên tắc DRY\n\nDo not repeat yourself - đó là một trong những nguyên tắc đầu tiên bạn được dạy khi là software engineer. Nó được nhúng sâu vào bản thân chúng ta đến nỗi ta không thể chịu được việc có thêm vài dòng code. Mặc dù nhìn chung là một rule tốt và fundamental, khi overuse nó dẫn đến cognitive load mà ta không thể handle.\n\nNgày nay, mọi người build software dựa trên các component tách biệt về mặt logic. Thường chúng được phân phối giữa nhiều codebase đại diện cho các service riêng. Khi bạn cố gắng loại bỏ mọi repetition, bạn có thể tạo ra tight coupling giữa các component không liên quan. Kết quả là, thay đổi ở một phần có thể có hậu quả ngoài ý muốn ở các khu vực khác có vẻ không liên quan. Nó cũng có thể cản trở khả năng replace hoặc modify từng component mà không ảnh hưởng toàn bộ hệ thống. `🤯`\n\nThực tế, vấn đề tương tự nảy sinh ngay cả trong một module đơn lẻ. Bạn có thể extract common functionality quá sớm, dựa trên sự giống nhau có thể không thực sự tồn tại về lâu dài. Điều này có thể dẫn đến các abstraction không cần thiết khó modify hoặc extend.\n\nRob Pike từng nói:\n\n> A little copying is better than a little dependency.\n\nChúng ta bị cám dỗ để không reinvent bánh xe mạnh đến nỗi sẵn sàng import các library to nặng để dùng một function nhỏ mà ta dễ dàng viết được.\n\n**Tất cả dependency của bạn là code của bạn.** Đi qua 10+ level của stack trace của library đã import và tìm ra chỗ sai (*vì mọi thứ đều sai*) rất đau đớn.\n\n## Tight coupling với framework\nCó rất nhiều \"magic\" trong framework. Bằng cách dựa quá nhiều vào framework, **ta buộc tất cả developer sau này phải học \"magic\" đó trước.** Có thể mất hàng tháng. Mặc dù framework cho phép ta launch MVP trong vài ngày, về lâu dài chúng có xu hướng thêm complexity và cognitive load không cần thiết.\n\nTệ hơn, tại một thời điểm nào đó framework có thể trở thành constraint đáng kể khi đối mặt với requirement mới không fit architecture. Từ đây mọi người fork framework và maintain custom version của riêng họ. Tưởng tượng lượng cognitive load mà một newcomer phải build (tức là học custom framework này) để deliver bất kỳ value nào. `🤯`\n\n**Chúng ta hoàn toàn không advocate việc invent mọi thứ from scratch!**\n\nTa có thể viết code theo cách hơi framework-agnostic. Business logic không nên nằm trong framework; thay vào đó, nó nên dùng các component của framework. Đặt framework ra ngoài core logic của bạn. Dùng framework theo kiểu library. Điều này cho phép contributor mới add value từ ngày đầu tiên, không cần phải đi qua debris của framework-related complexity trước.\n\n> [Why I Hate Frameworks](https://minds.md/benji/frameworks)\n\n## Layered architecture\nCó một sự hào hứng về engineering đối với tất cả thứ này.\n\nBản thân tôi từng là người ủng hộ nhiệt thành Hexagonal/Onion Architecture trong nhiều năm. Tôi dùng nó ở đây và kia và khuyến khích các team khác làm như vậy. Độ phức tạp của project tăng lên, số lượng file tăng gấp đôi. Cảm giác như ta đang viết rất nhiều glue code. Với requirement thay đổi liên tục, ta phải thay đổi qua nhiều layer của abstraction, tất cả trở nên tẻ nhạt. `🤯`\n\n**Abstraction được cho là ẩn complexity, ở đây nó chỉ thêm [indirection](https://fhur.me/posts/2024/thats-not-an-abstraction).** Nhảy từ call này sang call khác để đọc theo và tìm ra chỗ sai và thiếu cái gì là requirement quan trọng để nhanh chóng giải quyết vấn đề. Với việc layer uncoupling của architecture này, nó cần một factor exponential của các trace thêm, thường không liên tục, để đến điểm xảy ra lỗi. Mỗi trace như vậy chiếm chỗ trong limited working memory của ta. `🤯`\n\n\n
\n
\n
\n
\n Nguyên tắc coding và kinh nghiệm
\n \n
\n
\n\nInvolve junior developer vào architecture review, họ sẽ giúp bạn identify các khu vực mentally demanding.\n\n**Maintaining software rất khó**, mọi thứ break và ta cần mọi bit mental effort mà ta có thể tiết kiệm. Càng ít component trong hệ thống, càng ít issue sẽ có. Debug cũng sẽ ít mentally taxing hơn.\n\n> Debug khó gấp đôi so với viết code ngay từ đầu. Do đó, nếu bạn viết code clever nhất có thể, theo định nghĩa, bạn không đủ thông minh để debug nó.\n>\n> *Brian Kernighan*\n\nNhìn chung, mindset \"Wow, architecture này chắc chắn cảm thấy tốt!\" rất misleading. Đó là cảm giác chủ quan \"tại một thời điểm\", và nó không nói gì về thực tế. Approach tốt hơn nhiều là quan sát hậu quả về lâu dài:\n- Có dễ reproduce và debug issue không? Hay bạn phải nhảy qua call stack hoặc distributed component, cố gắng hiểu mọi thứ trong đầu?\n- Ta có thể thay đổi nhanh không, hay có nhiều unknown unknown, và mọi người sợ touch mọi thứ?\n- Người mới có thể add feature nhanh không? Có unique mental model nào cần học không?\n\nNhững câu hỏi này khó track hơn nhiều, và mọi người thường không thích trả lời chúng trực tiếp. Nhìn vào một vài software system phức tạp nhất thế giới, những thứ đã vượt qua thử thách của thời gian - Unix, Kubernetes, Chrome và Redis (xem comment bên dưới). Bạn sẽ không tìm thấy gì fancy ở đó, phần lớn là nhàm chán, và đó là điều tốt.\n\n## Kết luận\nTưởng tượng một chốc rằng cái mà ta suy ra trong chương thứ hai thực ra không đúng. Nếu vậy, thì kết luận mà ta vừa phủ định, cùng với các kết luận trong chương trước mà ta đã chấp nhận là hợp lệ, có thể không chính xác. `🤯`\n\nBạn cảm thấy nó chứ? Không chỉ bạn phải nhảy khắp bài để lấy nghĩa (shallow module!), mà đoạn văn nói chung khó hiểu. Chúng ta vừa tạo ra unnecessary cognitive load trong đầu bạn. **Đừng làm điều này với đồng nghiệp.**\n\n\n
\n
\n Comment
\n
\n Rob Pike (Unix, Golang)
Bài viết hay.
\n Andrej Karpathy (ChatGPT, Tesla)
Bài post hay về software engineering. Có lẽ là quan điểm đúng nhất, được thực hành ít nhất.
\n Elon Musk (Rocket)
Đúng.
\n Addy Osmani (Chrome, software system phức tạp nhất thế giới)
Tôi đã thấy vô số project nơi developer thông minh tạo ra architecture ấn tượng bằng design pattern mới nhất và microservice. Nhưng khi team member mới cố gắng thay đổi, họ mất hàng tuần chỉ để hiểu mọi thứ fit với nhau như thế nào. Cognitive load cao đến nỗi productivity giảm mạnh và bug nhân lên.
\n Mỉa mai? Nhiều pattern gây complexity này được implement với danh nghĩa \"clean code.\"
\n Điều thực sự quan trọng là giảm unnecessary cognitive burden. Đôi khi điều này có nghĩa là ít module sâu hơn thay vì nhiều shallow module. Đôi khi có nghĩa là giữ logic liên quan với nhau thay vì tách thành các function nhỏ.
\n Và đôi khi có nghĩa là chọn solution nhàm chán, straightforward hơn là clever. Code tốt nhất không phải elegant hoặc sophisticated nhất - đó là code mà developer tương lai (bao gồm cả bạn) có thể hiểu nhanh chóng.
\n Bài viết của bạn thực sự cộng hưởng với các challenge chúng tôi đối mặt trong browser development. Bạn hoàn toàn đúng về browser hiện đại là một trong những software system phức tạp nhất. Quản lý complexity đó trong Chromium là challenge liên tục align hoàn hảo với nhiều điểm bạn đưa ra về cognitive load.
\n Một cách chúng tôi cố gắng handle điều này trong Chromium là thông qua component isolation cẩn thận và well-defined interface giữa các subsystem (như rendering, networking, JavaScript execution, v.v.). Tương tự ví dụ deep module của bạn với Unix I/O - chúng tôi aim cho powerful functionality đằng sau interface tương đối đơn giản. Ví dụ, rendering pipeline của chúng tôi handle incredible complexity (layout, compositing, GPU acceleration) nhưng developer có thể tương tác với nó thông qua clear abstraction layer.
\n Các điểm của bạn về tránh unnecessary abstraction cũng rất trúng. Trong browser development, chúng tôi liên tục cân bằng giữa làm codebase approachable cho contributor mới trong khi handle inherent complexity của web standard và compatibility.
\n Đôi khi solution đơn giản nhất là tốt nhất, ngay cả trong complex system.
\n antirez (Redis)
Hoàn toàn đồng ý :) Ngoài ra, cái tôi tin là thiếu trong \"A Philosophy of Software Design\" đã đề cập là khái niệm \"design sacrifice\". Tức là, đôi khi bạn sacrifice thứ gì đó và nhận lại simplicity, hoặc performance, hoặc cả hai. Tôi áp dụng ý tưởng này liên tục, nhưng thường không được hiểu.
\n Một ví dụ tốt là việc tôi luôn từ chối có hash item expire. Đây là design sacrifice vì nếu bạn có certain attribute chỉ trong top-level item (các key chính chúng), thiết kế đơn giản hơn, value sẽ chỉ là object. Khi Redis có hash expire, đó là nice feature nhưng yêu cầu (thật vậy) nhiều thay đổi cho nhiều part, tăng complexity.
\n Một ví dụ khác là cái tôi đang làm ngay bây giờ, Vector Set, Redis data type mới. Tôi quyết định rằng Redis sẽ không là source of truth về vector, mà nó chỉ có thể lấy approximate version của chúng, nên tôi có thể làm on-insert normalization, quantization mà không cố gắng retain large float vector trên disk, v.v. Nhiều vector DB không sacrifice việc nhớ cái user đưa vào (full precision vector).
\n Đây chỉ là hai ví dụ random, nhưng tôi áp dụng ý tưởng này ở mọi nơi. Bây giờ vấn đề là: dĩ nhiên người ta phải sacrifice đúng thứ. Thường có 5% feature chiếm very large amount của complexity: đó là thứ tốt để kill :D
\n Một developer từ internet
Bạn sẽ không hire tôi... Tôi bán mình dựa trên track record của các enterprise project đã release.
\n Tôi làm việc với một người có thể nói về design pattern. Tôi không bao giờ có thể nói kiểu đó, mặc dù tôi là một trong số ít có thể hiểu anh ta rõ ràng. Các manager yêu thích anh ta và anh ta có thể dominate bất kỳ development conversation nào. Những người làm việc xung quanh anh ta nói anh ta để lại trail of destruction phía sau. Người ta nói với tôi rằng tôi là người đầu tiên có thể hiểu project của anh ta. Maintainability quan trọng. Tôi quan tâm nhất về TCO (Total Cost of Ownership). Với một vài firm, đó là thứ quan trọng.
\n Tôi đăng nhập Github sau khi không ở đó một thời gian và vì lý do nào đó nó đưa tôi đến một bài trong repository của ai đó có vẻ random. Tôi nghĩ \"cái gì đây\" và gặp chút rắc rối để đến home page, nên tôi đọc nó. Tôi không thực sự register nó vào lúc đó, nhưng nó tuyệt vời. Mọi developer nên đọc nó. Nó phần lớn nói rằng hầu như mọi thứ chúng ta được nói về programming best practice dẫn đến \"cognitive load\" quá mức, có nghĩa là đầu óc của chúng ta bị đá bởi intellectual demand. Tôi đã biết điều này một thời gian, đặc biệt với các demand của cloud, security và DevOps.
\n Tôi cũng thích nó vì nó mô tả practice tôi làm trong hàng thập kỷ, nhưng không bao giờ thừa nhận vì chúng không popular... Tôi viết stuff thực sự phức tạp và cần mọi help tôi có thể nhận được.
\n Cân nhắc, nếu tôi đúng, nó pop up vì các Github folk, những người rất thông minh, nghĩ rằng developer nên thấy nó. Tôi đồng ý.
\n Comment trên Hacker News (2)
\n \n"
},
{
"path": "README.zh-cn.md",
"content": "# 认知负荷才是关键\n\n[Prompt](https://github.com/zakirullin/cognitive-load/blob/main/README.prompt.md) | [Blog version](https://minds.md/zakirullin/cognitive) | [Chinese](https://github.com/zakirullin/cognitive-load/blob/main/README.zh-cn.md) | [Japanese](README.ja.md) | [Spanish](README.es.md) | [Korean](README.ko.md) | [Turkish](README.tr.md) | [Vietnamese](README.vi.md) | [Nepali](README.np.md)\n\n*这是一份持续更新的文档，最后更新：**2025 年 10 月**。欢迎你的贡献！* \n\n*本译文基于原文 [6df913d](https://github.com/zakirullin/cognitive-load/commit/6df913dc1c1bf63dfe5933144155908ce68f6808) 版本进行翻译。*\n\n## 简介(Introduction)\n这世上充斥着各种流行术语与“最佳实践”，但大多数最终都失灵了。究其原因，在于这些理念往往只是想象中的图景，而非源自现实。它们建立在美学偏好与主观判断之上。我们需要更基础、更不可能出错的东西。 \n\n有时我们在阅读代码时会感到困惑。困惑消耗时间和金钱。困惑源于过高的“认知负荷”。它不是某种花哨的抽象概念，而是**人类的一种基本约束。** 它不是臆想出来的，它的确存在，而且我们能真切感受到。 \n\n鉴于我们在阅读与理解代码上所花费的时间远多于书写代码所花费的，我们应当持续地自省：我们是否正在把过多的认知负荷添加到代码中。 \n\n## 认知负荷(Cognitive load)\n> 认知负荷是指开发者为了完成一项任务需要动多少脑子。\n\n阅读代码时，你会把变量的取值、控制流逻辑、调用序列等“装”进脑子里。普通人的工作记忆大约能同时容纳[四个这样的信息块](https://github.com/zakirullin/cognitive-load/issues/16)。一旦认知负荷接近这个阈值，理解就会变得困难得多。\n\n*假设我们被要求去修补一个完全陌生的项目。有人告诉我们，之前有位非常聪明的开发者贡献过：用了很多酷炫的架构、花哨的库、时髦的技术。也就是说，**作者为我们制造了极高的认知负荷。***\n\n\n
\n
\n 认知负荷与打断
\n \n
\n
\n\n> 我们会以一种非正式的方式使用“认知负荷”这个术语；有时它与认知负荷的科学概念一致，但我们并不确切知道在哪些地方一致、哪些地方不一致。\n\n## 认知负荷的类型(Types of cognitive load)\n**内在负荷(Intrinsic)**——由任务本身的固有难度引起。它不可消减，是软件开发的核心所在。 \n\n**外在负荷(Extraneous)**——由信息的呈现方式引入。由与任务不直接相关的因素造成，比如“聪明作者”的各种癖好。它可以被大幅削减。本文将聚焦于这种外在认知负荷。 \n\n\n
\n
\n
\n
\n 重要的事物应当有足够的分量，丰富的示例
\n
\n \n
\n
如果你允许那些关键的核心函数（“关键点”）写得长一些（“粗糙”一点），反而更容易在茫茫函数之海中将其识别出来，它们的重要性一目了然：看，它们体量庞大，显然不同凡响！
\n 这张图取自 《Codin' Dirty》 由 Carson Gross编写。你将在这里找到大型函数(deep functions)的真实世界案例。\n \n\nP.S. 如果你以为我们是在为臃肿、职责过多的“万能对象”摇旗呐喊，那你就误解了。\n\n## 关于“仅为一件事负责” (Responsible for one thing)\n我们常常遵循一种模糊的原则，结果造出一堆浅模块：“一个模块应该只负责一件事，而且仅此一件”。但这“一件事”到底是什么？实例化一个对象也算一件事，对吧？那么 [MetricsProviderFactoryFactory](https://minds.md/benji/frameworks) 就理所当然？**这类类名和接口带来的心智负担，往往比它们整个实现还高——这算什么抽象？** 哪儿不对劲了。 \n\n我们修改系统是为满足用户和利益相关方的诉求。我们应当对他们负责。 \n\n> 一个模块应当且只应当对一个用户或利益相关方负责。 \n\n这才是单一职责原则(SRP)的真正内涵。通俗地说，如果我们在一个地方引入了 bug，然后两位不同业务条线的人都来投诉——我们就违反了该原则。它与我们在模块中做了多少事情无关。 \n\n但即便如此，这条规则也可能“利少弊多”。每个人对它的理解都不尽相同。更好的做法是看它们带来了多少认知负荷。记住“一个地方的变更会在不同业务流中引发一串连锁反应”本身就很费脑力。就这样，无须再学什么花哨术语。 \n\n## 过多的“浅微服务” (Too many shallow microservices)\n“浅-深模块”原则与规模无关，同样适用于微服务架构。浅微服务太多，毫无益处——行业正朝着某种“宏服务”发展，即不那么浅(=更深)的服务。最糟且最难修复的现象之一是所谓“分布式单体”，它往往源于过度细粒度、过度浅化的拆分。\n\n我曾为一家初创公司做咨询，五个开发做了 17(！)个微服务。他们比计划落后了 10 个月，离正式发布遥遥无期。每个新需求都需要修改 4+ 个微服务。在这样一个分布式系统里，复现和调试一个问题要花掉极长时间。正式推出的估时和认知负荷都高得令人无法接受。`🤯` \n\n这是应对新系统不确定性的正确方式吗？在一开始就厘清正确的逻辑边界极其困难。关键是在合理的范围内尽可能晚地做决定，因为那时你手头掌握的信息最多。若一上来就引入网络层，我们的设计决策从一开始就变得难以回退。团队给出的唯一理由是：“FAANG(脸书、亚马逊、苹果、网飞和谷歌)证明了微服务架构是有效的”。*醒醒吧，别再做不切实际的美梦了。*\n\n[Tanenbaum-Torvalds 辩论](https://en.wikipedia.org/wiki/Tanenbaum%E2%80%93Torvalds_debate)曾指出，Linux 的单体设计有缺陷且过时，应改用微内核架构。确实，从“理论与美学”的角度看，微内核似乎更优。然而从实践的角度看——三十年过去了，基于微内核的 GNU Hurd 仍在开发中，而单体结构的 Linux 无处不在。你现在阅读的这个网页由 Linux 伺服，你的智能茶壶都跑在 Linux 上，单体的 Linux。\n\n经过精心设计，由模块良好隔离的单体系统，往往比由众多微服务组成的架构更灵活，维护所需的心智负担也更小。只有当“独立部署”的需求变得至关重要时(比如团队规模扩张)，才应考虑在模块之间加入网络层，逐步演进为未来的微服务。\n\n## 特性丰富的编程语言(Feature-rich languages)\n当喜欢的语言发布新特性(Feature) 时，作为开发者我们往往会很兴奋。我们会学习它们，并在代码里用起来。\n\n如果特性很多，我们可能会花费半小时，通过写几行代码来试试某个功能或者另一个功能。这多少有点浪费时间。但更糟的是，**等你过一阵子再回头看，你还得重新推演一遍当时的思路！**\n \n**你不仅要理解这个复杂的程序，还得搞明白：当时写代码的人，为什么会觉得用这些特性来解决问题是个好办法。** `🤯`\n\n这些话来自 Rob Pike。\n\n> 减少选择，就能降低认知负荷。 \n\n编程语言的特性是很好的，只要这些特性之间互不干扰。 \n\n\n 一位拥有 20 年 C++ 经验的工程师的想法 ⭐️
\n
\n 前几天我看我的 RSS 阅读器，发现“C++”标签下居然有三百来篇未读文章。我从去年夏天起就没读过一篇关于 C++ 的文章，而且我觉得我的感觉一如既往的好！
\n 我用 C++ 已经 20 年了，差不多是我人生的三分之二。我的大部分经验都花在语言的边边角角(各种未定义行为)上。这不是可复用的经验，如今要把它们全都丢下，多少有点奇怪和不安。
\n 比如你能想象吗，|| 在 requires ((!P<T> || !Q<T>)) 和 requires (!(P<T> || Q<T>)) 中含义不同。前者是约束析取(constraint disjunction)，后者是我们熟悉的逻辑或运算符，而且它们的表现是不同的。
\n 你不能仅仅为一个平凡类型(trivial type) 分配内存然后直接 memcpy 将字节复制过去——那并不会启动对象的生命周期。这在 C++20 之前是这样的。在C++20的版本里修了，但语言的认知负荷却只增不减。
\n 即便有些问题被修正了，认知负荷却在不断增加。作为专业的开发者，我需要知道什么被修了、何时修的、修之前是什么样。没错，C++ 对遗留的特性支持很好，这也意味着你得直面那些遗留。例如上个月同事问了我一个 C++03 的行为。🤯
\n 以前有 20 种初始化方式。后来加了统一初始化语法。现在我们有 21 种了。顺带一提，还有谁能记住从初始化列表里选择构造函数的规则吗？好像是跟隐式转换和“信息损失最小”有关，但如果值在编译期是已知的，那就是另一回事了……🤯
\n 这些额外的认知负荷并非来自当前的业务任务，也不是领域的内在复杂性。它只是因为历史原因而存在的(外在负荷)。
\n 我不得不定些规则。比如，如果某行代码不那么一目了然，我还得去回忆标准，那我最好别那样写。顺便说，标准大概 1500 页。
\n 我绝不是在指责 C++。我热爱这门语言。只是我累了。
\n 感谢 0xd34df00d 的来稿。
\n \n\n## 业务逻辑与HTTP状态码(Business logic and HTTP status codes)\n在后端我们返回： \n`401` 表示 JWT 令牌过期 \n`403` 表示权限不足 \n`418` 表示用户被封禁 \n\n前端的工程师在实现登录功能时，会用到后端 API。于是他们必须在脑子里临时记住这样一组映射：\n`401` 表示 JWT 令牌过期 // `🧠+`，好，先记着 \n`403` 表示权限不足 // `🧠++` \n`418` 表示用户被封禁 // `🧠+++` \n\n前端开发者(希望如此)会在代码里放一个“数字状态码 -> 语义”的映射，这样后面加入的贡献者就不用再在脑子里重新构建这套映射关系了。\n\n然后 QA 进场： \n“嘿，我遇到 `403`，这是令牌过期还是权限不足？” \n**QA 不能马上开始测试，因为他们得先重建后端工程师当初在脑中构建的认知负荷。**\n\n为什么要把这种自定义映射强行塞进我们的记忆中呢？更好的做法是把业务细节从 HTTP 传输协议中抽离，直接在响应体里返回自描述的代码：\n```json\n{\n \"code\": \"jwt_has_expired\"\n}\n```\n\n前端侧认知负荷：`🧠`(清空，脑中无须再记映射) \nQA 侧认知负荷：`🧠`\n\n同样的规则适用于各种“数字类型的状态码”(无论在数据库里还是别处)——**优先使用自描述的字符串。** 我们早就不处在需要为 640K 内存做优化的年代了。\n\n> 人们会为 `401` 和 `403` 争论不休，依据各自的心智模型(mental model) 下判断。新的开发者加入后，他们又得重新推演一遍当时的思路。也许你写了架构决策文档(Architecture Decision Record, ADR)来记录“为什么”要这样做，帮助新人理解当时的决策。但归根结底，这并不明智。我们可以大体把错误分成“用户相关”和“服务器相关”，除此之外，界线其实很模糊。 \n\nP.S. 区分“authentication”和“authorization”本身就令人头大。用更简单的词比如[“登录”(login)和“权限”(permissions)](https://ntietz.com/blog/lets-say-instead-of-auth/)可以降低认知负荷。\n\n## 滥用 DRY 原则(Abusing DRY principle)\n\n“不要重复你自己”(Do not repeat yourself, DRY)——这是作为软件工程师最早学到的原则之一。它深入骨髓，以至于我们难以容忍多出的几行重复代码。尽管它总体上是个良好且基础的准则，但过度使用会带来难以承受的认知负荷。\n\n如今大家都基于逻辑上分离的组件构建软件。它们往往分布在多个代码库中，代表不同的服务。当你致力于消除一切重复时，可能最终会在本不相关的组件之间建立起紧耦合。结果是，一个地方的变更会在其他看似无关的地方产生意想不到的后果。这也会阻碍单独替换或修改某个组件的能力，因为它会牵一发而动全身。`🤯` \n\n事实上，即使在单个模块内，也会出现同样的问题。你可能会基于一些看起来相似但长远来看根本不存在的共性而会过早地抽取出所谓的“通用功能”。这会导致产生一些不必要的抽象，难以修改或扩展。\n\nRob Pike 说过：\n\n> 适度的复制好过引入新的依赖\n\n我们常常过于抗拒“重复造轮子”，以至于为了使用一个很小的函数，不惜引入庞大而笨重的库。而这些库我们本可以轻松自己写出来。\n\n**你的依赖库，也是你代码的一部分。** Bug 来去无踪，不可预测，当你为了定位问题的根源而不得不翻阅某个依赖库的的十几层调用链时，你会知道什么叫做折磨。\n\n## 框架的紧耦合(Tight coupling with a framework)\n框架里有很多“魔法”(A.K.A. 奇技淫巧)。当我们过度依赖某个框架时，**会迫使后来的开发者先去学习这些魔法。** 这可能要花上几个月。虽然框架能让我们在几天内推出 MVP，但从长远看，它们往往带来不必要的复杂性与认知负荷。\n\n更糟糕的是，当遇到一个与架构格格不入的新需求时，框架可能会成为最大的约束。于是人们开始 fork 框架并维护自有的定制版。想象下新人要积累多少认知负荷(也就是学会这个定制框架)才能产出价值。`🤯`\n\n**当然，我们绝不是提倡从零开始造轮子！！**\n\n我们可以以相对“框架无关”的方式编写代码。业务逻辑不应被放在框架内部；相反，它应该仅使用框架的组件。把框架放在核心逻辑之外，用它像用库(library)一样。这样一来，新加入的贡献者从第一天就能带来价值，而不需要先在框架的复杂细节中摸爬滚打。 \n\n> [《为什么我讨厌“框架”》](https://minds.md/benji/frameworks)\n\n## 分层架构(Layered architecture)\n这些东西，确实能让工程师的肾上腺素飙一飙。\n\n我自己曾经是六边形架构(Hexagonal Architecture) / 洋葱架构(Onion Architecture) 的热情拥护者，持续了好几年。这里用、那里也用，还鼓励其他团队用。随后项目复杂度上去了，单看文件数量就翻了一倍。我们像是在写大量“胶水代码”。在需求持续变更的背景下，我们得在多层抽象里同时改动，一切变得繁琐乏味。`🤯`\n\n**抽象本应隐藏复杂性，但这里它只是增加了[间接层](https://fhur.me/posts/2024/thats-not-an-abstraction)。** 要快速定位问题，理解哪里出错了、缺了什么，通常需要沿着调用链逐步跟踪。但在这种分层架构中，层与层之间的解耦导致我们需要额外的、甚至割裂的多层调用链来找到错误点。每一条这样的调用链，都会占据我们有限的工作记忆。`🤯`\n\n\n
\n
\n> problem space: 问题空间，简单理解就是当前环境下业务所面临的一系列问题和背后的需求。
\n> solution space: 解决方案空间，则是针对问题空间的解决方案，它思考的是如何设计实现软件系统以解决这些问题，它属于工程设计实施阶段，通常是技术专家主导的解决方案设计和实现。\n\n通用语言(ubiquitous language)、领域(domain)、有界上下文(bounded context)、聚合(aggregate)、事件风暴(event storming)——这些都属于问题空间的范畴。它们帮助我们洞悉领域、划定边界。DDD 让开发者、领域专家与业务人员能用一种统一语言高效沟通。然而，相较于关注这些问题空间的方面，我们常常强调特定的文件夹结构、服务(service)、仓库(repository) 以及其他解决方案层面的技术，而忽略了DDD在问题空间上的问题。\n\n问题在于，我们对 DDD 的理解往往是独特且主观的。如果我们在这种理解的基础上去写代码，就会制造大量额外的认知负荷 —— 未来的开发者只能陷入困境。`🤯` \n\nTeam Topologies 提供了一个更好、更易理解的框架，帮助我们在团队之间分担认知负荷。工程师在学习 Team Topologies 后，往往能形成较为接近的心智模型。相比之下，DDD 往往让 10 个读者形成 10 种不同的理解。它本该是“共同语言”，结果却成了“辩论场”.\n\n## 熟悉的项目中的认知负荷(Cognitive load in familiar projects)\n\n> 问题在于，**熟悉并不等于简单。** 二者给人的*感觉*看似是一样的 —— 都让人不用费太多脑力就能轻松的在代码之间穿梭 —— 但原因完全不同。你使用的每一个看似“聪明”(其实是“自我炫技”)且非大家惯用的技巧，都会让别人付出额外的学习成本。一旦他们学会了，那与代码相处就没那么难了。这就是为什么你很难看出如何简化你已经熟悉的代码。我会尽量让“新来的开发者”在他们还没被环境同化之前来评审代码！ \n>\n> 之前的作者很可能是一点点把代码写乱的，而非一次性造成的。你可能是第一个必须一次性搞清楚整个烂摊子的人。\n>\n> 我在课堂上描述过某天遇到的一个冗长 SQL 存储过程，其巨大的 WHERE 子句里有数百行条件。有人问，怎么会有人让代码变得这么糟。我告诉他们：“当只有两三个条件时，再加一个没什么差别；当有二三十个条件时，再加一个也没什么差别！” \n>\n> 在代码库里，没有任何“简化的力量”会自动发生。唯一能让代码变简单的，就是你自己做出的有意识的选择。简化需要付出努力，而人们往往无暇顾及。\n>\n> —— 感谢 [Dan North](https://dannorth.net) 的评论。 \n\n如果你已把项目的心智模型(mental model) 内化到长期记忆里，你就不会感到高认知负荷。 \n\n\n
\n
\n 编码原则与经验
\n \n
\n
\n\n在架构评审中让初级开发者参与进来，他们能帮你识别出那些对脑力要求很高的部分。\n\n**维护软件很难**，总会出问题，我们需要尽可能节省每一分心力。系统组件越少，问题也就越少。调试也会更省心。 \n\n> 调试的难度是写代码的两倍。因此，如果你把代码写得尽可能“聪明”，那意味着你根本不够聪明去调试它。\n>\n> *Brian Kernighan*\n\n总体而言，抱着 “哇，这个架构真舒服！”这样的心态是有误导性的。那只是“某一时刻”的主观感受，丝毫不能代表现实。更好的方法是长期观察它的后果：\n- 问题是否易于复现和调试？还是你不得不穿梭于多层调用栈或分布式组件之间，在你脑海中试图拼凑出完整的调用链路？\n- 我们能否快速进行修改？还是说，系统中存在大量未知的不确定性，导致大家不敢轻易调整？\n- 新人能否快速添加功能？是否有一些独特的心智模型需要学习？\n\n这些问题很难追踪，人们也往往不愿直接回答。看看世界上最复杂且经得住时间考验的软件系统——Unix、Kubernetes、Chrome 和 Redis(见下方评论)。你不会在它们身上找到什么花哨的东西——大多“很无聊”，这恰恰是好事。\n\n## 结论(Conclusion)\n想象一下，如果我们在第二章里推断出的结论其实并不正确。那意味着，我们刚刚否定掉的结论，以及之前章节里我们认为正确的那些结论，也可能都不成立。`🤯` \n\n感受到了吗？你不仅需要在文章中来回跳转才能抓住意思(浅模块！)，而且这个段落本就难懂。我们刚刚在你的脑中制造了不必要的认知负荷。**不要把这种事加诸在你的同事身上。**\n\n\n
\n
\n 评论
\n
\n Rob Pike (Unix, Golang)
好文章.
\n Andrej Karpathy (ChatGPT, Tesla)
一篇关于软件工程的好文。也许是最真实、却最少被践行的观点。
\n Elon Musk (Rockets)
确实如此。
\n Addy Osmani (Chrome，世界上最复杂的软件系统之一)
我见过无数项目中，聪明的开发者用最新的设计模式和微服务构建了令人印象深刻的架构。但当新成员尝试做改动时，他们花了好几周也只是试图弄清楚各部分如何拼在一起。认知负荷高到离谱，生产力直线下降，bug 倍增。
\n 讽刺的是？许多引入复杂性的模式，都是以“整洁代码”的名义被实施的。
\n 真正重要的是减少不必要的认知负担。有时这意味着用更少、更“深”的模块替代许多“浅”的模块。有时这意味着把相关逻辑放在一起，而不是拆成无数微小函数。
\n 有时这也意味着选择无聊、直接的方案而非聪明的方案。最好的代码并非最优雅、最复杂的——而是未来的开发者(包括你自己)能很快看懂的代码。
\n 你的文章让我非常有共鸣，尤其是对于我们在浏览器开发中面临的挑战。你说现代浏览器是最复杂的软件系统之一，这完全正确。管理 Chromium 的复杂性是一项持续的挑战，也与文中关于认知负荷的许多观点高度契合。
\n 我们在 Chromium 中处理复杂性的做法之一，是谨慎的组件隔离和在子系统(如渲染、网络、JavaScript 执行等)之间定义清晰的接口。这类似你关于 Unix I/O 的“深模块”例子——我们追求在相对简单的接口背后提供强大的功能。比如，我们的渲染管线处理着令人难以置信的复杂性(布局、合成、GPU 加速)，但开发者可以通过清晰的抽象层与之交互。
\n 你关于避免不必要抽象的观点也很扎心。在浏览器开发中，我们持续在“让代码库对新贡献者更友好”与“处理网络标准和兼容性的内在复杂性”之间做平衡。
\n 有时，在复杂系统里，最简单的方案才是最好的。
\n antirez (Redis)
完全同意 :) 我认为《A Philosophy of Software Design》里欠缺的一个概念是“设计牺牲”。也就是，有时你牺牲一些东西，换来简单、性能，或两者兼得。我一直都在践行这个理念，但它常常不被理解。
\n 一个例子是，我一直拒绝让哈希字段(hash items)支持过期。这是一次“设计牺牲”，因为如果某些属性只存在于顶层条目(键本身)，设计更简单，值就只是对象。当 Redis 引入哈希字段过期时，功能是不错，但确实需要在许多地方做很多改动，复杂性上升。
\n 另一个例子是我正在做的 Vector Sets，新的 Redis 数据类型。我决定 Redis 不做向量的“事实来源(source of truth)”，而只是存储近似版本，因此我可以在写入时做归一化、量化，而无需在磁盘上保存大规模的浮点向量等等。很多向量数据库不会牺牲“保留用户放入的全精度向量”这点。
\n 这只是两个随机例子，但我到处都在应用这种理念。关键是：当然要牺牲对的东西。往往 5% 的特性就占据了非常大比例的复杂性：那正是该砍掉的 :D
\n 一位来自互联网的开发者
你们可能不会雇我……我靠“发过多少企业项目”这类履历吃饭。
\n 我曾和一个能“说设计模式”的人共事。我从来不会那样说话，尽管我是少数能很好理解他的人之一。管理者很喜欢他，他能主导任何开发讨论。但周围人说，他走到哪儿都留下一地鸡毛。别人说我是第一个能理解他项目的人。可维护性很重要。我最在乎 TCO (总拥有成本)。对很多公司来说，这才重要。
\n 我很久没上 Github 了，某次登录后不知为何跳到某个看起来随机的人仓库里的文章上。我在想“这是什么”，又一时回不了主页，于是就读了。起初没在意，但它太棒了。每个开发者都该读一读。它基本告诉我们：几乎我们被灌输的所有编程最佳实践，都会导致过量的“认知负荷”，意思是我们的脑子被过度的消耗。我早就有这感觉，尤其在云、安全、DevOps 的要求下。
\n 我也喜欢它，因为它描述了我几十年来一直在做、但不太好意思承认(因为不流行)的实践……我写的东西非常复杂，需要尽可能多的帮助。
\n 想想看，如果我是对的，那它会出现在 Github 首页，是因为 Github 的聪明人觉得开发者应该看看它。我赞同。
\n Hacker News 上的评论(2)
\n \n"
}
]