LUA best practices and clean code

Naming, structure, testing, refactoring, dependency boundaries, and readable architecture.

Chapter goal: Naming, structure, testing, refactoring, dependency boundaries, and readable architecture.

Simple explanation

Clean code is code that another person can understand and safely change. Clear names and small responsibilities matter more than clever tricks.

In LUA, this chapter is about writing code future-you can safely change. Start with the idea above. Then connect each symbol to a value or action in the example.

Do not try to remember every symbol. First ask what data the program has, what it does with that data, and what result it creates. Technical words become easier when you connect them to those three questions.

Why this topic is important

Expert code is not only clever; it is clear, tested, and easy to maintain. In LUA, the syntax may look different from other languages, but the thinking skill transfers: name the data, choose the right operation, and make the next step obvious.

When to use it

Use these habits on every real project, especially when features grow and multiple people work together.

Example code

local function calculateTotal(points, bonus)
  return points + bonus
end

local function printResult(name, total)
  print(name .. ": " .. total)
end

Line-by-line explanation

• local function calculateTotal(points, bonus) — This defines a reusable function. Its name describes the job that other code can call.
• return points + bonus — This sends a result back to the code that called the function. Returning is different from printing.
• end — This line supports one focused piece of application logic. Read it together with the block directly around it.
• local function printResult(name, total) — This is the visible output line. It shows the final value after the earlier work is complete.
• print(name .. ": " .. total) — This is the visible output line. It shows the final value after the earlier work is complete.
• end — This line supports one focused piece of application logic. Read it together with the block directly around it.

What the output means

No visible output is guaranteed by this partial snippet. Its result is stored or returned for another part of the program.

The output is evidence that the program followed the instructions. If your result is different, read from the first line and write down how each value changes. That is debugging, not failure.

Mistake example

local function calculateTotal(points, bonus)
  return points + bonus
end

local function printResult(name, total)
-- Removed required line: a vague name hides the responsibility of the code
end

This version intentionally shows how a vague name hides the responsibility of the code. The changed assignment stores a missing value, or a required line is removed, so later code cannot complete its job safely.

Fixed version

local function calculateTotal(points, bonus)
  return points + bonus
end

local function printResult(name, total)
  print(name .. ": " .. total)
end

The corrected version restores the real value or required operation. It fixes the chapter-specific problem: a vague name hides the responsibility of the code.

Common mistakes

• Optimizing before understanding the problem.
• Creating abstractions for one use case.
• Leaving behavior untested when it affects users.

Warning: Change one part at a time. If you change many lines together, it becomes harder to learn which change caused the result.

Real use cases

• Prepare interview-ready code.
• Maintain a growing app.
• Refactor AI-generated code safely.

Practice exercise

1. Rename one unclear variable so its purpose is obvious.
2. Split one long function into two smaller, named functions.
3. Add a comment only where the reason is not obvious from the code itself.

Tip: If the exercise feels too large, complete only steps 1 to 3. Small working code teaches more than a large unfinished project.

Mini quiz

1. Find the bug: what is unclear about a function named doStuff?
2. Choose the correct fix: split the function, or add a comment explaining its five jobs?
3. Explain a real scenario: why does a clear name reduce how many comments you need?

How to read AI-generated code

Do not copy AI code first. Read it like a detective. Find the data, follow the changes, and locate the final output. Ask AI to explain a line only after you have made your own guess.

• What data goes in?
• What values are stored?
• What calculation or decision happens?
• What is printed, displayed, saved, or returned?
• What can go wrong?
• Can you rename one value and still explain the code?

RedM safety check

RegisterCommand creates a named command. Its callback receives source (who triggered it) and args (the words after the command). Client code handles the local player's screen and input. Server code owns trusted game state. Never trust prices, rewards, permissions, or item counts sent by a client; check them again on the server.

Before you move on

• I can explain this topic in my own words.
• I can read the small example without AI.
• I can change the example and predict the new result.
• I can find and fix one simple mistake.
• I can name one real project that uses this idea.

Next topic

Next, learn software architecture. Before opening it, explain this chapter out loud in under one minute.