Episode 4: AI-Ready Engineering: Let the Variables Tell the Story
Most codebases have a particular kind of comment that looks like this:
// Check if amount is over the limit
if amount > 10000
The comment repeats the code, and the code repeats the comment, a breathtaking collaboration. Neither one tells us which amount we mean, which limit applies, or what happens once we cross it.
In Episode 3, "Explicit Beats Clever in an AI-Assisted Codebase," we looked at keeping a system's behavior visible. This episode zooms in on names. Earlier episodes covered readability in general; here the focus is domain vocabulary, and how much of the business a codebase can explain through the names it uses.
What: If Code Needs Commentary, Its Names Are Not Finished
Comments often get treated as documentation, and sometimes they are. Just as often, they patch over code that did not say what it meant.
Comments are allowed. The risk is that they drift away from the code while still looking authoritative. Someone updates the logic, the comment stays the same, and now the system tells two stories, one of which is wrong.
That is awkward for humans and worse for AI, because AI is very good at treating confident-looking text as useful context. If the variable says amount, the literal says 10000, and the comment says limit, the reader still has to piece together the business meaning.
Putting that meaning into the code removes the guesswork:
const regulatoryReviewThreshold = 10000
const requiresRegulatoryReview = transactionAmount > regulatoryReviewThreshold
Now the code says what the amount represents, what the threshold represents, and which decision follows.
Why: Humans and AI Follow the Vocabulary You Give Them
A codebase teaches people how the system thinks, and its names become the product's vocabulary. Words like customer, subscription, renewal window, and grace period are the domain model.
Precise vocabulary lets an engineer follow the logic without six open tabs. AI benefits from the same precision. Hand an AI tool code full of data, temp, result, flag, and process, and it has to infer the domain from behavior alone. Sometimes it gets that right, and sometimes it produces a very polished misunderstanding.
Vague names leave room for plausible guesses. Specific names take that room away.
Compare these two conditions:
if flag && days > 30
if daysPastDue > paymentGracePeriodInDays
The first makes the reader reverse-engineer a rule, while the second states it outright. A good name keeps intent at the exact place where intent affects behavior.
Naming Business Rules in NetSuite Scripts
NetSuite scripts make the cost of vague names easy to see. Custom field IDs start with prefixes like custbody_ or custentity_ and often end with whatever someone typed on a busy Friday. Reading them straight into conditions spreads that vagueness through the whole script. Here is the core of a user event script that flags a sales order for credit review.
Before:
const amount = ctx.newRecord.getValue('custbody_amt2');
// Check if amount is over the limit
if (amount > 10000) {
ctx.newRecord.setValue({ fieldId: 'custbody_flag', value: true });
}
After:
const orderAmount = ctx.newRecord.getValue('custbody_amt2');
const creditReviewThreshold = Number(
runtime.getCurrentScript().getParameter({ name: 'custscript_credit_review_threshold' })
);
const requiresCreditReview = orderAmount > creditReviewThreshold;
if (requiresCreditReview) {
ctx.newRecord.setValue({ fieldId: 'custbody_flag', value: true });
}
The field IDs stay as they are in the account, but each value now has a business name, so the next reader, human or AI, gets the business term instead of the field ID. The threshold moves into a script parameter, so the number can change without a code change, and the name tells reviewers which rule it controls.
How: Turn Implementation Details Into a Story
Self-documenting code does not require enormous variable names. The goal is for each important step to say what role it plays.
Name what values and functions mean
Names like data, value, item, and result describe the shape of the box and say nothing about its contents. Domain names do much better:
const eligibleRenewals = subscriptions.filter(isEligibleForRenewal)
We started with subscriptions, picked the ones eligible for renewal, and the variable name confirms what came out. Functions follow the same rule: a function called processData says nothing, while calculateRenewalQuote or scheduleRegulatoryReview says what the system is trying to accomplish. When functions, variables, and types share one vocabulary, the codebase reads like a coherent explanation.
Turn booleans into sentences
A boolean should make a condition read like a decision:
const hasOutstandingBalance = outstandingBalance > 0
const isWithinRenewalWindow = daysUntilExpiry <= renewalWindowInDays
const canAutoRenew = isWithinRenewalWindow && !hasOutstandingBalance
Read those aloud, and the rule explains itself. If a condition is hard to read aloud, name the decisions inside it.
Replace magic values with domain concepts
A bare number is evidence of a rule somebody once knew. A retry count of 3 or a retention period of 30 means something to someone, so make that meaning visible:
const retryLimitForPaymentGateway = 3
const abandonedCartRetentionDays = 30
The value may change over time, and the concept should outlive it. And when the concept changes, the name helps reviewers notice that the business rule changed too.
Use intermediate variables to reveal the plot
Engineers sometimes squeeze a whole decision into one expression because it is technically possible. So is eating soup with a fork. Intermediate variables let the logic unfold in steps:
const activeSubscriptions = subscriptions.filter(isActive)
const subscriptionsNearExpiry = activeSubscriptions.filter(isWithinRenewalWindow)
const renewalCandidates = subscriptionsNearExpiry.filter(hasValidPaymentMethod)
Each line answers one question and sets up the next. A human reviewer can check the logic step by step, and an AI tool gets a much cleaner map of the transformation.
Treat comments as a warning light
Before adding a comment, check whether the code can carry the meaning instead.
- Can the variable be renamed?
- Can the condition become a named boolean?
- Can the magic value become a domain constant?
- Can the block become a function whose name states the decision?
If yes, improve the code.
Some reasons do live outside the code, such as a vendor defect, a regulatory citation, a protocol constraint, or a deliberate workaround with an expiry date. Those deserve a comment the team will maintain. The code should say everything else.
Good Code Tells the Plot
Name the decision, and the code explains the business.
At ATSOURCE, we build NetSuite teams that write code whose names explain the business it runs. Let's talk about what that looks like for your organization.
Meet the Author
Jona has over a decade of experience in SuiteCloud Development on the NetSuite platform. She specializes in implementing advanced solutions and has led teams in creating high-quality software. Jona holds multiple certifications and has been recognized with awards like the Summit Award and Quality Champion Award.
Tags
Accelerate ERP Success with Expert Solutions
Ready to put what you've learned into practice? ATSOURCE delivers both the specialized talent and comprehensive NetSuite support you need to turn strategy into results.Connect with our experts today and move from planning to performance.
