The One Naming Convention That Will Transform Your Machine Learning Code
markdown formatted blog content
Let's be honest — debugging neural network code is hard enough without fighting against cryptic variable names. You've been there: staring at outputs, trying to remember if it's batch-first or batch-last, whether it includes the sequence dimension, or if someone reshaped it somewhere you forgot to check.
There's a better way, and it's absurdly simple.
What Are Shape Suffixes?
Shape suffixes are lowercase letter codes appended to tensor variable names that describe their dimensions. Instead of outputs, you write outputs_bc. Instead of activations, you write activations_bcn.
At first glance, this might look like extra typing. Trust me — it's the opposite. It's one of the most impactful coding conventions you can adopt for machine learning projects.
The Dimension Dictionary
Here's the standard alphabet for tensor dimensions:
- b — batch dimension
- p — position or sequence index
- n — neuron dimension (typically the result of a weight matrix multiplication)
- c — channel dimension
- h — height (for image tensors)
- w — width (for image tensors)
- d — depth (for 3D data)
- k — kernel dimension
So logits_bc tells you it's a batch of logits with channel dimensions — perfect for classification tasks. positional_embeddings_bpn means you have batch, position, and neuron dimensions in that order.
Why This Convention Pays Off
Immediate context. When you see probs_bc, you instantly know you're looking at probabilities organized by batch and class. No guessing, no documentation hunting.
Built-in error detection. This is where it gets powerful. If you write outputs_bc = torch.matmul(activations_bcn, weights_bcn), the mismatch jumps out immediately. Your weight matrix should be weights_nc to properly multiply with activations_bcn. The names themselves become a static type checker for tensor shapes.
Self-updating documentation. Comments become stale. Nobody updates them when they refactor. But embeddings_bpn stays accurate as long as you maintain the convention — because the variable name IS the documentation.
Smoother code reviews. Reviewers can spot dimension mismatches in pull requests without running code or tracing through function calls. This saves everyone time and catches bugs earlier.
Practical Patterns to Adopt
For concatenations and stacks: When you combine tensors, update the suffix to reflect the new structure. Stack two features_bc tensors along a new dimension? Now it's features_bck or features_bkc depending on which axis you chose.
For reductions: Sum over the position dimension and your inputs_bp becomes inputs_b. Take argmax across channels and logits_bc becomes logits_b. The suffix shrinks to match reality.
For complex tensors: You can stack multiple dimension codes: attention_bpp for attention scores across position pairs, or gradients_bpn for gradients organized by batch, position, and neuron.
Making It Stick
The key is consistency. Pick the convention, apply it everywhere — inputs, outputs, and every intermediate tensor. Yes, including that one-liner variable you临时 created just to debug something.
Your future self will thank you. So will your teammates.
If you're building ML applications and want clean, maintainable code that scales with your team, these small conventions compound into massive productivity gains. It's the same principle behind good naming anywhere in software development — make the code read like documentation.
Give it a week in your next project. I think you'll wonder how you ever coded without it.