Why do we write what we write?

Table of Contents

• Introduction
• Philosophers
  • Sartre
  • Kierkegaard
  • Jeremy Bentham
• Software Engineering Writers
  • Andrew Hunt & David Thomas
  • Martin Fowler
    • Code Smell Examples
  • RobertC. Martin
  • Donald Knuth
• What I think
  • Continuous Delivery
  • Why do we write what we write?
• Programming and Writing Guide for AI
• Bibliography

Introduction

Code is the historical record artifact of problem-solving.

It tells a story: of care, affection, organization and technique; or of promises, secrets, despair and chaos.

Code is a gift: for you and for the project contributors.

Now, whether it's a Trojan horse, mysterious, or a wedding gift, that's your choice.

Philosophers

I read a book about the history of philosophy, which is practically a summary of the main Western thinkers, from Socrates to Alan Turing.

I'll address some of the thoughts from the book that I found pertinent to Software Engineering.

Let's go:

Sartre

According to Sartre, we humans are condemned to be free; that is, we are all obligated to make decisions.

And the lack of decision is also a choice.

Like NULL, in a createdAt column, of an existing row in the database.

Kierkegaard

Kierkegaard said: "choose or don't choose, it doesn't matter, you will regret it."

If we are forced to choose and every choice will result in regret, why not make the best choice?

And how to know what the best choice is?

Jeremy Bentham

In philosophy, a guy named Jeremy Bentham proposed a solution.

The best choice is the one that generates the greatest "positive effect" for society, taking into account people, animals, and the environment.

"Greatest happiness for the greatest number."

In Software Engineering, some authors have also addressed good social practices (but focused on code projects).

Software Engineering Writers

Andrew Hunt & David Thomas

In the book The Pragmatic Programmer, they defend the idea that programming is like tending a garden, constantly getting rid of pests/weeds.

They also present the broken windows theory, which suggests that a destroyed/messy environment tends to get worse over time. It's easy to dirty an environment that's already dirty, but no one wants to be the first person to put dirty dishes in a clean sink.

They complain about the artificial urgency imposed by tech companies and argue that: "Every deadline is malleable" and few computing sectors are truly critical (like health, transportation, aviation).

Martin Fowler

Explains what code smells are and defends the idea of constant improvement through small iterative changes and lots of automated tests.

"If it's smelling bad, change it"

Code Smell Examples

• Mysterious name
  • dataItem, infoList, DataItemComponentPropHelper,
• Duplicate code
• Long function
• Long parameter list
• Global data
• Mutable data

RobertC. Martin

RobertC. Martin advocates the "good neighborhood" policy: "Always leave the code cleaner than you found it" and argues that part of a Senior developer's responsibilities is to say: No.

"The only way to go fast is to go right".

Donald Knuth

Writer of the grand book series: The Art of Computer Programming (classic reference in Computer Science) advocates the study of mathematics for programmers and states that "the root of all evil is premature optimization".

What I think

Sartre: Absolute freedom, anxiety of decision. Kierkegaard: Choosing or not choosing, there will always be the pain of the path not taken. Bentham: Choose thinking about the good of the majority

The uncertainty after changing an unstable project without test coverage is distressing.

I like the garden analogy for projects (Hunt/David), it combines with the idea of continuous improvement in micro changes (Fowler) and good neighborhood (Robert C. Martin).

It resembles Bentham's ideals (acting for the majority).

Kierkegaard encourages you to choose the best option without fear of making mistakes, since error is inevitable 😅😅😅

That said,

• Choose seeking meaning (justification) and not happiness.
• Don't optimize anything without a metric behind it.
• To measure, you need: observability.
• Be careful with DRY (Don't Repeat Yourself), be more adept to YAGNI (You Ain't Gonna Need It).
  • Implement the same code 2-3 times before decoupling, it's easier to see the pattern with more samples 😁

I've been using ADRs (Architectural Decision Records) to organize strategic project decisions, they become a history of the project's choices and their reasons.

Continuous Delivery

Frequent micro-changes require automated test pipelines to ensure continuous integration

The larger the test scope, the more confidence it provides. A mocked test may have its validity but little impact on delivery confidence.

An e2e (end-to-end) test, without mocked services, provides great value to the project, even with the inconvenience of initial setup.

Unit testing is good for preventing bug recurrence and documenting complex functions. Otherwise, I prefer integration or E2E testing.

It's worth noting that it's not always up to the programmer to decide the delivery pace and task priority. The world is not a strawberry.

However, you can still (in fact, are forced to) make your decisions, since you'll have to live with their consequences.

Why do we write what we write?

Code is a shortcut.

When writing a function, you have the maximum context about that task, and this contextual memory gets worse over time.

Spend 5 more minutes thinking about the code situation, after it's already working. Ask it: Does it make sense? Can you read it? Is there duplication? Is it meaningful? Will I understand it in 6 months?

The Red-Green-Refactor strategy from TDD insists that rewriting is part of the process.

It's necessary to rename, move, decouple, delete and simplify the records of problem solutions, so that it becomes a story told through files, neither too small nor too large.

Unlike Clean Code, I don't advocate minuscule files, I find large files acceptable, as long as they are descriptive.

But then: Why do we write what we write?

I don't know about you, but I write/program to avoid the future mental fatigue of relearning what has already been learned.

Use the right tools: Github Actions for CI/CD, Docker for your environments and observability tools for your peace of mind.

And so, I'm finishing here: We write to record what will soon no longer belong to our memory.

And you, what do you think? Why do we write what we write?

Programming and Writing Guide for AI

I created a programming and writing guide for AI (designed for Claude Code) with concepts I think are important 😁.

It has the following sections:

• Git Workflow
• Coding Guidelines
  • TypeScript/JavaScript
  • React
• Software Programming
• Testing
• Writing
• Naming

It costs R$19.90 and you help me continue writing about: AI tools, software engineering books, philosophy, physics and astronomy, from a curious person's point of view.

Bibliography

A Brief History of Philosophy

Starts with Socrates (I only know that I know nothing) and goes to current questions about AI (whether they can think or not). Goes through all the great Western philosophers (Europeans), the ones I liked most were: Socrates, Aristotle, Spinoza, Bentham, John Stuart Mill, Darwin, Hegel, Marx, Sartre. The book fails by not including any Eastern, Latin American or African philosophers.

Why do we do what we do

Refactoring

Clean Code

The Pragmatic Programmer

Note: Links contain affiliate coupons