Lua Best Practices: Do's and Don'ts for Clean, Performant Code in Game Dev & Scripting

## Naming Conventions
**Do:** Adopt snake_case for variables and functions, PascalCase for modules, UPPERCASE for constants, and prefix private items with underscore. Use descriptive names.
Example:
```lua
local user_name = "player1"  -- Good
local MAX_LIVES = 3          -- Good
local _private_helper = function() end  -- Good
```
**Don't:** Mix cases or use vague names like 'x' or 'tmp'.
Example:
```lua
local UserName = "player1"  -- Bad, inconsistent
local x = 10                -- Bad, not descriptive
```

## Code Organization
**Do:** Group related functions into modules, use local functions for privacy, section code with comments, and limit file size. Rely on require() for dependencies.
Example:
```lua
-- player_module.lua
local Player = {}
function Player.new(name)
  local self = {name = name}
  return self
end
return Player
```
**Don't:** Pollute global namespace or cram everything into one file.
Example:
```lua
-- Bad: globals everywhere
globalPlayer = {}  -- Avoid
```

## Error Handling
**Do:** Wrap risky calls in pcall/xpcall, use assert() for checks, handle nils explicitly, and log errors.
Example:
```lua
local ok, result = pcall(function() return riskyFunc() end)
if not ok then
  print("Error: " .. tostring(result))
end
assert(type(input) == "string", "Input must be string")
```
**Don't:** Ignore errors or use bare calls that crash.
Example:
```lua
riskyFunc()  -- Bad, unhandled
```

## Performance Optimization
**Do:** Prefer locals, pre-allocate tables, use table.concat() for strings, avoid globals and loop table creation.
Example:
```lua
local t = {} for i=1,100 do t[i] = i end  -- Pre-allocate
local str = table.concat(parts, " ")     -- Efficient concat
```
**Don't:** Rely on globals or inefficient string ops.
Example:
```lua
str = str .. part  -- Bad in loops
```

## Memory Management
**Do:** Clean up resources, use weak tables, avoid cycles, clear unused refs, monitor in long apps.
Example:
```lua
local weak = setmetatable({}, {__mode = "v"})  -- Weak values
obj.ref = nil  -- Clear ref
```
**Don't:** Create circular refs or leak memory.
Example:
```lua
a.obj = b; b.obj = a  -- Bad cycle
```

## Testing & Documentation
**Do:** Test units, edges, integrations; comment params/returns, explain logic, add examples.
Example:
```lua
-- function add(a: number, b: number): number
-- Adds two numbers.
-- @param a First number
-- @param b Second number
-- @return Sum
function add(a, b) return a + b end
```
**Don't:** Skip tests or leave undocumented code.
Example:
```lua
function add(a,b) return a+b end  -- Bad, no docs
```

## Security & Lua-Specific
**Do:** Validate inputs, avoid loadstring, use metatables wisely, stick to 1-based indexing, leverage tables.
Example:
```lua
if type(input) ~= "string" then error("Invalid input") end
local mt = {__index = default}
```
**Don't:** Trust user input or misuse globals/metatables.
Example:
```lua
loadstring(user_code)()  -- Dangerous
```

## Game Dev Patterns
**Do:** Structure game loops, efficient collisions, state management, optimized renders/inputs.
Example:
```lua
function love.update(dt)
  -- Update logic
end
```
**Don't:** Busy-wait loops or naive collision checks.