stone
Back to Articles

Naming Things Is Engineering

Naming is not decoration in Stone. It is part of the engineering system.

An engineering platform lives or dies by whether people can understand it later: the person reviewing a model, the researcher checking a derivation, the engineer debugging a result at midnight, the AI assistant tracing intent across a project, and the company that needs years of technical knowledge to remain legible instead of turning into folklore.

That is why Stone treats names as infrastructure.

We maintain naming guidelines for the standard library and slabs because names decide whether a codebase becomes a map or a maze. A good name lets a reader move through a model without translation. A bad name makes every line ask for a private glossary.

The Philosophy

Stone names should be readable and self-documenting.

The rule of thumb is simple:

Is this name a genuine scientific, mathematical, or programming standard, or is it tool-specific shorthand?

If a name is standard across textbooks, papers, major tools, and working technical practice, Stone keeps it. Names like fft, svd, pid, linspace, and meshgrid are not arbitrary abbreviations. They are part of the shared vocabulary.

But if a name is shorthand inherited from old character limits, one tool's private habits, or a desire to make the line shorter at the cost of the reader, Stone spells it out.

That is why Stone prefers:

group_delay
nelder_mead
magnitude_squared
distance

over names like:

grpdelay
fminsearch
mag_sq
dist

The goal is not to be verbose. The goal is to make the obvious thing obvious.

The Cost Of Finding Out

Over-abbreviation looks efficient at the point of writing, but most code is read far more often than it is written. Saving a few characters in dist is rarely worth making every later reader ask whether it means distance, distribution, distortion, or something local to one slab.

That cost is not dramatic, which is why it is easy to ignore. It appears as small interruptions: checking documentation, searching the repository, scanning nearby examples, or remembering that a term meant one thing in MATLAB and another thing in a local package. Those interruptions increase mental burden without improving the model, the algorithm, or the result.

For humans, clearer names make code cleaner because the meaning stays on the page. For AI tools, the same names provide better semantic signal when the model moves between code, documentation, tests, examples, and version history. In both cases, the benefit is ergonomic: fewer pauses, fewer private translations, and less context that has to be reconstructed from elsewhere.

Names Are A Trust Surface

Technical software asks users to trust calculations, models, transformations, and results. That trust is not only about algorithms. It is also about whether the system tells the truth at the surface.

A name should tell the reader what kind of thing they are looking at:

  • A boolean query reads like a question: is_stable, has_column.
  • A conversion says where it goes: to_matrix, rgb_to_hsv.
  • An operation is a verb: normalize, rotate, fillet, extrude.
  • A value is a noun: magnitude, distance, energy.
  • A variant keeps the noun first: magnitude_squared.
  • A builder that adds a named component uses with_: with_column, with_species.

This grammar matters because it makes APIs predictable. Once you learn the pattern, you can often guess the next name before looking it up.

We Do Not Copy Incumbents Blindly

Stone learns from existing tools, but it does not cargo-cult them.

MATLAB, Python, Julia, C, Fortran, CAD kernels, solver packages, and domain libraries all contain useful precedent. They also contain history: character limits, old parser constraints, inherited abbreviations, naming collisions, and ecosystem-specific habits.

Stone's naming process asks what the term means now, to a competent reader in the relevant domain.

Some short names are good:

fft
svd
dof
rgb
freq
coeff
tol
max_iter

Some short names are not:

dist   // distance? distribution?
temp   // temperature? temporary?
pos    // position? positive?
vol    // volume? volatility?
sq     // square? squared? sqrt?
spec   // specification? spectrum?
mag    // magnitude? magnetic?

When a truncation has more than one plausible reading, Stone spells it out.

Why Stone Writes to

MATLAB has many real conversion names where 2 means "to": rgb2hsv, cart2pol, tf2ss, cell2mat, table2array, and num2str. Inside MATLAB, that convention is familiar, and it made sense in the history that produced those APIs.

Stone chooses the conversion word instead:

rgb_to_hsv
cartesian_to_polar
transfer_function_to_state_space
cell_to_matrix
table_to_array
number_to_string

The issue is not that 2 is impossible to understand. The issue is that digits already do important work in technical code. They can mark dimensions in names like draw2d, canvas3d, conv2d, and vec3; they can mark orders, model families, and compact domain terms; and they can appear in names that are not conversions at all.

Writing to removes that ambiguity. In rgb_to_hsv, the relationship is explicit. In cartesian_to_polar, the coordinate systems are not compressed into a private convention. In transfer_function_to_state_space, the name still reads clearly to someone who understands control systems but has not memorised a particular API's shorthand.

Stone still uses 2d and 3d when the dimension is the point. The distinction is useful: digits can mean dimensions, and to can mean conversion. The reader should not have to decide which one a name meant.

Names Follow The Shape Of The Domain

Stone does not force one naming style everywhere. The name form follows the model of the slab.

In fluent modelling slabs, the pipe already says "act on this thing", so operations are bare verbs:

part = box([1, 2, 3])
    |> fillet(0.1)
    |> rotate([0, 0, 1], 45)

with_fillet would be noise. The function transforms the part, so fillet is the right name.

In data-builder slabs, a function that returns a copy with a named component uses with_:

table2 = table1 |> with_column("mass", masses)
model2 = model1 |> with_species("A")

Here with_ carries meaning: the value is being described by its named parts.

That distinction is important. Stone is immutable, so set_ is almost never the right name. set_ implies mutation. Stone either transforms a value with a verb or returns a new value with a component added through with_.

Namespace Carries Context

Stone uses modules for namespacing. Functions do not repeat the module name.

Inside a sparse module:

solve
transpose
add

is better than:

sp_solve
sp_transpose
sp_add

The call site already carries the domain when the user wants it:

import sparse
x = sparse.solve(A, b)

The same rule keeps broader slabs clean:

import chem
water = chem.formula("H2O")
mw = chem.molar_mass(water)

The module name is the prefix. We do not smuggle the prefix into every function.

One Concept, One Form

Consistency is not the same as copying a legacy API. Consistency means that once Stone chooses the clearest form for a concept, that form is used everywhere.

If the concept is distance, Stone should not scatter dist, distance, and d across different slabs.

If the table-domain term is col, then the family should line up:

col
num_col
with_col
has_col
col_count

not drift into:

column
num_column
ncols
with_col

Readers build trust when related things line up.

Module Names Stay Small

Slab names are one lowercase token:

linalg
stats
signal
geometry
materials
multibody
timeseries

Plural names are reserved for catalog-like slabs or discipline words where the plural is the field name, such as materials, mechanics, dynamics, robotics, and physics.

Process and method slabs stay singular:

integrate
optimize
signal
mesh
flow
geometry

The question is: does the slab contain a catalog of named things, or does it do something?

Commodity Names And Branded Names

Some slabs implement commodity domains. Nobody needs a branded name for linear algebra. The name should say what is inside:

linalg
fft
stats
signal
interpolate

Other slabs are opinionated. They encode a workflow, a way of modelling, or a set of product decisions. Those slabs deserve names with character.

clay is the example: it is not merely "cad". It is a parametric modelling workflow built around source, features, sketches, solids, and simulation-ready geometry. Calling it cad would claim the whole domain. Calling it clay says: this is our modelling material, and this is our way of shaping it.

The test is:

Could someone build a competing slab in the same domain with different opinions?

If yes, the slab probably needs a name of its own.

Parameters Are Different

Stone keeps scientific variable conventions where they genuinely help:

n
m
i
x0
dt
Ts
tol
max_iter
A
b

Parameters are closer to mathematical notation than public API nouns. A function signature like:

fn fsolve(F, x0, tol = 1e-12, max_iter = 100)

is clearer than one that spells out every mathematical convention in prose.

The rule is not "never abbreviate." The rule is "abbreviate only when the abbreviation is the clearest name for the audience."

Honest Parameters

Names are also promises.

If a function accepts method = "linear", then method should represent a real choice. A parameter with exactly one working value is not future-proofing. It is a false promise.

Stone avoids:

interp(x, y, xi, method = "linear") // if "linear" is the only implemented method

until there is at least a second real method.

The same applies to ignored knobs. A levels parameter that the body never reads is worse than missing functionality. It tells the user something exists when it does not.

Naming discipline and implementation honesty are the same habit: do not make the surface lie.

Why We Publish This

Naming can sound like an internal style preference. For Stone, it is part of the product promise.

Stone is meant to be a transparent technical platform. That transparency includes algorithms, validation, types, packages, visualisations, version history, and AI context. It also includes the words we choose.

When names are systematic:

  • Documentation becomes easier to scan.
  • AI can infer intent more reliably.
  • Users can guess APIs from nearby APIs.
  • Slabs feel like one platform instead of unrelated packages.
  • Reviewers can discuss models without translating private jargon.
  • Technical knowledge survives longer than the original author.

That is why Stone naming is procedural rather than taste-based. We classify the thing, choose the grammatical form, decide whether an abbreviation is genuinely standard, let the namespace carry context, enforce consistency, and only then format the identifier.

The result is a library that reads like engineering, not like archaeology.

The Standard We Are Holding Ourselves To

Stone's naming guidelines are not a one-time cleanup pass. They are part of how we build the system.

Every public slab, every exported type, every function, every parameter, every return record, every module name, and every example is part of the same surface. If that surface is coherent, users feel it immediately. If it is inconsistent, users pay for it forever.

So we are proud to be fussy about names.

Good names are not polish after the engineering work. They are engineering work.