When engineers say "self-documenting code," they usually mean something like this: readable code with good naming conventions, small functions with clear responsibilities, and minimal or no comments. The reasoning is that comments go stale, but code is always up to date. So the code should be the single source of truth.

There is real value in this. Readable code is easier to work with than unreadable code. Good naming helps. Small functions help. None of that is wrong.

But there is a quiet assumption hiding underneath: that if you can read what the code does, you also know what it is supposed to do. That assumption is where things fall apart.

Code describes what it does. It can tell you that a function takes two numbers and returns their sum. It can tell you that a loop iterates over a list and filters out entries matching some condition. It can tell you the exact sequence of operations that will execute at runtime.

What it cannot tell you is whether any of that is correct.

Correctness is not a property of code in isolation. It is a relationship between the code and something external to it: the intent. What was this supposed to do? What problem was it meant to solve? For whom? Under what circumstances?

Code is an interpretation of intent. It is not the intent itself.

Consider the requirement: "write a program that models a car."

One engineer builds a model with parts: engine, wheels, chassis, doors. The model captures the structure of a car. It would work well for a sales catalog or a parts inventory system.

Another engineer builds a model with behaviors: accelerate, brake, steer, shift gears. This model captures what a car does. It would work well for a driving simulation.

Both implementations are clean. Both have good names, clear structure, small functions. Both are, by any reasonable standard, "self-documenting." And both are completely correct — for different intents.

If you only have the code, you cannot tell which one is right. You might not even realize there is a question to ask. A confident engineer could build the wrong system and never notice, because the code reads perfectly well.

Intent is the purpose behind the code. It answers questions like: what problem are we solving, who has this problem, and how will we know we solved it?

You cannot derive intent from code. You can read the code and understand what it does, but you cannot reconstruct why it was written that way, or whether the approach was the right one. The code is a finished product. The reasoning that led to it is not embedded in the artifact.

This is the core of the fallacy: treating the artifact as if it contains the reasoning. It doesn't.

The same pattern shows up in other places.

Tests written after the implementation tend to mirror the code they are testing. They verify that the code does what the code does. This is circular. A test that says "the function returns 42" is only useful if you know that 42 is the right answer. Without intent, the test is a tautology.

Commit messages often describe what changed but not why. "Refactored user service" or "updated validation logic" tells you what happened in the code. It does not tell you what motivated the change, what problem it addressed, or what trade-offs were considered. Six months later, the commit is a fact without context.

Code reviews suffer from the same gap. A reviewer can check whether the code is clean, whether it follows conventions, whether there are obvious bugs. But without knowing the intent, the reviewer cannot assess whether the code solves the right problem. The review becomes a style check.

You might think that specifications capture intent. Sometimes they do. But in practice, specifications often describe solutions rather than problems.

"Implement a car model with the following attributes: engine, wheels, chassis, doors." That is not intent. That is a design decision already made. The specification has absorbed the interpretation and presents it as if it were the requirement.

The same fallacy applies: the artifact is mistaken for the reasoning. A specification that describes a solution without explaining the problem it solves is just code written in prose.

In larger organizations, there are often several layers between the people who have the problem and the people who write the code. Product managers talk to stakeholders, write requirements, hand them to architects, who produce designs, which are passed to development teams.

At each step, the original problem gets translated. And at each translation, some intent is lost and some interpretation is added. By the time the requirements reach the engineers, they often look like solutions. The engineers implement them faithfully. The code is clean. The tests pass. The system ships.

And sometimes nobody uses it. Or it solves a problem that nobody actually had. Not because the engineers were incompetent, but because the intent was lost somewhere in the chain.

Software practices vary widely. Not every team has the luxury of direct access to users. Not every organization enforces clear documentation of intent. Under time pressure, the artifact becomes the deliverable and the reasoning behind it is treated as overhead.

Writing down intent takes effort. It requires understanding the problem well enough to articulate it, which is harder than it sounds. It is easier to write code that works than to explain why it should work that way.

So the fallacy persists not because people are careless, but because the conditions make it easy to skip the hard part.

Code is not the source of truth for intent. It never was. Readable code is valuable, but it is not sufficient. The artifacts we produce — code, tests, commits, specs — need to be complemented by explicit explanations of why they exist.

This does not mean writing novels in comments. It means answering a few questions and making the answers visible: what problem are we solving, for whom, and how will we know it worked?

The format matters less than the habit. A sentence in a commit message. A paragraph at the top of a specification. A comment that explains a non-obvious decision. These small acts of documentation are what connect the artifact to its purpose.

Code can explain itself. It cannot justify itself.

Without intent, correctness is undefined. And if correctness is undefined, it does not matter how clean the code is.

This is the first entry in what I am calling Software Malpractice. Not because I think engineers are negligent, but because some of our most cherished practices deserve a closer look.

For the Basic steps On 1, start by taking a step forward with the left foot and stepping with the ball of your foot on beat 1 and the pause comes in beats 4 and 8.

For reference, in the On 1 Basic, the pause is on beats 4 and 8. The goal is now to place the Pause in different beats, e.g., 1+5, 2+6, or 3+7.

I the following sections I will make the case that placing the pauses on different beats allows you to get a better feel of different instrumental rythms; for that I will be using the song Ay Mi Maria by Bloque53 as reference for the Tumba, Bass and Piano rythms.

1. you can use the same ideas of placing the pause on different beats when dancing On 2 and try to feel which instrument is emphasized for each given variation
2. two more ways to change the location of the pause is to step on the Clave beats; for this I typcally need additional technological aids to be able to hear the Clave, more info in Practice, practice, practice

You will need some good tunes to practice, I suggest you use music that is not too fast and song on which the the piano, bass, and Tumba rythms are easy to hear. I like to use Ay Mi Maria! by Bloque53.

For the Clave rythm I like to use an app like Salsa Rythm or The Salsa Beat Machine, you can control the speed and volume of each instrument! That has helped me a lot connect each timing of the pause to different instruments.

Now you have 6 ways to practice placing the pause:

1. 4 positions of the pause on the basic and
2. 2 positions when dancing on the clave beats (clave 2-3 and 3-2)

1. The step icons were taken from svg icons and are licensed by CC BY 4.0

Working as a software engineer can be stressful. The pace of modern/agile software teams is fast, bi-weekly sprints, continuous delivery, you build it … you run it, etc.. On top of that, having to learn the next programming tool/technique is very demanding.

I'm more of a thinker than a tinkerer; I like to look at topic from different angles, do some research, try a few experiments, step back and switch to something else while I let my brain process what I've learned, I might or might not come back to the topic depending on my level of interest or curiosity. My working preferences were not compatible with my programming job.

During my vacation around the end of 2021 I was going over my career prospects; I thought that I was ready to commit to a role long-term but I needed to do some research to understand my options and compare them somehow.

The first half of my career has been writing network clients and then writing application servers and release automation for the other half. I felt that I had been doing the same over and over only with different technologies and industry domains.

I didn't feel that I could make a drastic change like going out of the software scene since writing software was my main activity in the past 10 years. I am not a big risk taker so I only considered alternative paths that could benefit from my experience as a programmer.

I had narrowed down my options to two: software architecture and artificial intelligence.

In recent projects, my interest was often to get a glimpse of the high-level architecture and I would approach it by studying the delivery pipelines; when available, they describe the process each code change goes through to make it to a production environment.

Artificial Intelligence was interesting because it aligns well with personal interest in the automation of knowledge organization and discovery.

I found two resources that helped me Learn about what AI projects might look like in the industry:

1. Chollet's book: Deep Learning with Python: the Universal Machine Learning workflow was exactly what I was looking for at the time, a high-level overview of the life cycle of an ML Project.
2. Andrew Ng's content at deeplearning.ai: there I found descriptions of the different roles required to execute AI projects in the enterprise world. The site also has tools to asses your readiness for specific roles.

I was disappointed but not very surprised to learn that machine learning projects look very similar to other software projects.

AI/ML engineers bring their specialized skills to a project and were I to join an AI project, I would end up in a role almost indistinguishable to my current role, namely working on the delivery of AI-powered software to production environments.

During my vacation I made the resolution to double down and continue working as a software engineer and become even more proficient writing code for applications and release automation.

My resolution lasted about 4 hours after my return to work. On my first day after vacation, all it took was to read my mailbox and chat messages to remind me the many reasons why I was considering a change in the first place.

I started looking for a new role and that lead me into the world of IT infrastructure architecture. The company is large and for the past 50 years has deployed pretty much every piece of technology worth mentioning; my IT universe expanded and I felt quite good about not pursing AI/ML.

If you are considering a career in AI/ML, I highly recommend Chollet's book; it's a window into the world of machine learning engineering in the industry, directly from a very influential software engineer and AI researcher.

1. Deep Learning with Python
2. deeplearning.ai
3. François Chollet (Wikipedia)
4. posts with labels
   • #ai
   • #chollet
   • #software

Definition: Intelligence is the efficiency with which a learning system turns experience and priors into general skill at previously unseen tasks

Proponent: François Chollet

Proposed metrics: Skill Acquisition Efficiency (SAE)

Perspective: Emphasizes generalization and the ability to learn new tasks quickly from limited data.

Definition: Intelligence measures the ability of an agent to achieve goals in a wide range of environments

Proponent: Marcus Hutter

Proposed metrics: Universal Intelligence Measure (UIM); a formal mathematical definition summing over all computable reward functions weighted by their simplicity.

Perspective: Provides a formal, mathematical framework based on algorithmic information theory to define and measure intelligence.

Definition: Intelligence is the ability to generate novel, interesting actions or data by maximizing future expected reward or compression progress

Proponent: Jürgen Schmidhuber

Proposed metrics: Measures based on Compression Progress; improvement in predictive models driven by intrinsic motivation and curiosity

Perspective: Highlights the role of intrinsic motivation, curiosity, and data compression in discovering new patterns and behaviors.

Definition: Intelligence is often operationally defined by performance on specific tasks or benchmarks without a unified overarching definition

Proponent: Various

Proposed metrics: Task-specific metrics such as Accuracy, F1 Score, BLEU Score, etc., depending on the task

Perspective: Focuses on empirical performance in narrow domains, emphasizing results on established benchmarks over a holistic definition of intelligence

Definition: Intelligence is the capacity for reasoning, problem-solving, planning, abstract thinking, understanding complex ideas, and learning from experience

Proponent: Psychometrics

Proposed metrics: Intelligence Quotient (IQ); standardized tests measuring various cognitive abilities

Perspective: Emphasizes quantifiable cognitive abilities and compares individuals to population norms, focusing on human intelligence assessment

Definition: Superintelligence refers to an intellect that greatly surpasses the cognitive performance of humans in virtually all domains of interest

Proponent: Nick Bostrom

Proposed metrics: No specific metric; concept explores potential capabilities beyond human levels

Perspective: Focuses on the implications, risks, and ethics associated with creating intelligences that far exceed human cognitive abilities

Definition: Intelligence is the ability of an animal to adapt to its environment, learn from experiences, solve problems, and use tools

Proponent: Ethology

Proposed metrics: Behavioral tests assessing problem-solving, tool use, social learning, and communication abilities

Perspective: Studies intelligence across different species, emphasizing evolutionary adaptations and ecological contexts

Definition: Intelligence is the ability of an artificial agent to understand, learn, and apply knowledge in a general, human-like way across a wide range of tasks and domains

Proponent: Various

Proposed metrics: No standardized metric yet; Turing Test, general AI benchmarks, and evaluations across diverse tasks are used

Perspective: Aims to develop machines with general cognitive abilities comparable to humans, capable of understanding and reasoning across various contexts

The distinction between communication and documentation can be blurry for distributed teams. Recorded communication can be seen as extended documentation, at the same time, documentation is a form of communication.

Distributed teams can use recorded communication like chat, email, comments, etc. to bridge the gap created by geography. As long as communication is given priority over the tools or processes, the use of documentation as communication seems to maintain the spirit of the agile manifesto.

Some complex tasks require sharing context with multiple people. Consolidating context in a central location such as Jira/Wiki, makes it easier to onboard newcomers.

Distributed teams are often composed of individuals that participate in multiple projects simultaneously. Individuals who have to split their attention into multiple projects reduce the impact created by context switching by documenting useful details, such as the current status, and planned next steps.

For distributed teams, systems like Jira serve as a central place for coordinating work. I find it intriguing that people with technical IT skills often forget the value of systems like JIRA and at the same time they can deliver complex systems. Jira is bloated and could offer better user experience but it does not impose any workflow or methodology.

In principle, e-mail is sufficient. However, once you get used to the amenities of modern collaboration tools, it's hard to go back and use only e-mail. Popular collaboration tools seem to be converging in terms of features like creating a task from a chat conversation, tracking status, assigning, visualizing tasks and their relationships, linking to code or documentation, etc. Tools that started with one of these features continue adding more features until they cover all the basics of project management.

Companies arrive to systems like JIRA by taking a holistic/integrated approach. It's not perfect, but the available options are only a round of funding away from becoming like Jira.

Project management and collaboration is a complex domain, which explains why most tools offer a terrible user experience. I always remind myself that it could be worse, imagine doing project management only with email and PowerPoint.

Lena sat in the waiting room of NeuroLight Corporation, surrounded by holographic displays promoting the incredible achievements of those enhanced by the OptoCap.

"Ms. Torres?" called Ethan, a consultant with a polished demeanor. He ushered her into a futuristic office and gestured for her to sit.

“You’re about to unlock your full potential,” Ethan began, projecting an image of a brain onto the glass table between them. “The OptoCap can amplify your confidence, intelligence, creativity—whatever you need.”

Lena had always been cautious, but the promise of self-improvement was enticing. “Can it really make me more decisive?”

“With optogenetic programming, you can reshape your neural pathways to strengthen any trait you desire,” Ethan explained. “Imagine eliminating self-doubt or boosting your cognitive speed.”

Lena’s resolve hardened. “Let’s do it.”

The procedure was quick. Lena awoke feeling a slight weight on her head, her cap glowing faintly.

“Welcome to your new life, Lena,” Dr. Harmon, the chief scientist, said as he handed her a sleek control tablet. “With this, you can select programs to modulate brain states.”

Lena marveled at the array of options. She felt powerful, like an artist with an unlimited palette.

Within days, Lena transformed. Her confidence surged, making her an instant leader at work. The OptoCap’s programs allowed her to adjust her mood and cognition with a few taps.

At home, she selected the "Creative Boost" setting for an upcoming project. Waves of inspiration washed over her, unlocking ideas she never imagined.

One evening, as she explored deeper into her cap’s settings, Lena found an unfamiliar program. When she opened it, memories of board meetings and conversations she didn’t remember participating in flooded her mind.

Alarmed, Lena contacted Ethan. He arrived quickly, his usual composure replaced by nervousness.

“Lena, I assure you, everything is fine,” he began, but Lena cut him off.

“I found a program logging my thoughts. What is NeuroLight doing?”

Ethan hesitated. “There are built-in data collection systems. The company uses them to monitor user feedback…and sometimes influence.”

“Influence?” Lena repeated, incredulous. “You mean control.”

Ethan nodded, cornered. “It’s part of ensuring compliance and optimizing the system.”

Realization struck Lena—she was being manipulated. Her mind was not her own.

In the year 2160, the city of Aria stood as a beacon of progress and unity. Here, the Selected, a privileged class born sterile due to atypical sex differentiation, had risen to power. For centuries, they had been marginalized due to their inability to reproduce traditionally, but with advancements in genetic engineering, they found a new purpose.

The Selected devised a system where offspring were created through a combination of their original DNA and advanced genetic engineering. This method allowed the creation of highly adaptive, intelligent, and emotionally balanced humans who were celebrated as the "Neo-Gens." The old societal emphasis on sexual reproduction dwindled, as the Neo-Gens quickly demonstrated extraordinary talents and harmonious temperaments.

With the Selected in leadership positions, they shifted governmental incentives to focus on intellectual and creative contributions rather than traditional family structures. Those who excelled in arts, sciences, and community leadership were rewarded with resources and opportunities, fostering a society driven by merit and innovation.

As decades passed, the city of Aria flourished. Conflicts over resources diminished, as collaboration became the cornerstone of society. With genetic diversity and innovation at the forefront, diseases that plagued the human race for centuries were eradicated, and the environment thrived under careful stewardship.

Elders sat in the serene Gardens of Aria, observing children playing—a new generation that knew no prejudice or inequality. The Selected watched with pride, knowing they had not only survived but had reshaped humanity's fate.

By 2160, the Omega Line, once a marginalized class, defined by their sterility, had seized control of the city of Aria. With advancements in genetic engineering, they began creating offspring not through traditional means but by combining their DNA with engineered enhancements, producing the Neo-Gens.

The shift from sexual reproduction to engineered births led to societal unrest. Traditional families, feeling threatened by the new system, protested against what they saw as an erosion of human nature. The government, now dominated by the Omega Line, responded with strict laws that favored the Neo-Gens, marginalizing those who clung to old ways.

The promise of progress gave way to control. Society split into two classes: the genetically engineered Neo-Gens and the "Naturals," those born through traditional reproduction. Naturals faced increasing discrimination, relegated to menial jobs, and barred from leadership roles.

As the divide deepened, Aria became a city under surveillance, where dissenters were swiftly silenced. The Omega Line, in their bid to maintain control, implemented a draconian regime, manipulating genetics to create a generation of Neo-Gens devoid of free will.

Hope flickered among the Naturals, who formed underground resistance groups, determined to restore the balance and ensure diversity in human evolution. But the Omega Line's grip was strong, and for every small victory, the resistance suffered great losses.

Life continues in the city as the Omega Line maintains a firm grip on the government. Stories circulate about Normals walking among the general population, though no one has had direct contact with them since the fork.