THE CRAFT OF SOFTWARE

The first working version

A first version proves that an idea can function, but it rarely tells the whole story. Some shortcuts are useful while learning the problem. Before others depend on the software, revisit them and explain the assumptions they hide.

What happens when input is missing, when the network fails, or when a user takes an unexpected route? Craft begins when the code is shaped for these ordinary realities rather than only for the demonstration that made everyone smile.

Names are a design choice

A clear name saves a future reader from reconstructing a developer’s private thought. Variables, functions, and files form a small map of the system. Choose words that describe purpose, not only mechanics.

A comment can explain a constraint or a surprising business rule; it should not repeat a line that already says what it does. Readability is a practical kindness to the person who will fix a problem under time pressure, including your future self.

A relationship with errors

Errors are information about where a program meets the world. Handle them at the boundary where a useful decision can be made, and give people a message that helps them continue safely. Logs should tell a maintainer enough to diagnose the issue without exposing private data.

Good software does not promise never to fail. It makes failure understandable, contained, and less likely to repeat after someone learns from it.

Work that continues

Software rarely reaches a final, untouchable form. New users and changing needs will test earlier choices.

The most durable work is not the cleverest line but the structure that lets someone make a careful change later. That possibility is built one understandable decision at a time.

• Revisit prototype shortcuts before others rely on them.
• Name code for purpose and explain unusual constraints.
• Make errors useful without revealing private information.

The craft of code includes the person who must read it next.

— ARKI Editorial