---
id: daily-idiomatic-zener
name: "idiomatic-zener"
url: https://skills.yangsir.net/skill/daily-idiomatic-zener
author: diodeinc
domain: hardware
tags: ["hardware-development", "pcb-design", "documentation", "code-review"]
install_count: 724
rating: 4.20 (7 reviews)
github: https://github.com/diodeinc/pcb
---

# idiomatic-zener

> Zener 代码风格规范，包括无条件实例化、完整模式匹配和显式参数传递，确保代码一致性和可维护性

**Stats**: 724 installs · 4.2/5 (7 reviews)

## Before / After 对比

### 代码质量审查

**Before**:

代码风格不统一，条件实例化导致意外行为，模式匹配不完整引发运行时错误，调试一个模块需要 2 小时

**After**:

遵循统一风格规范，显式控制组件启用，完整模式匹配保证安全性，新代码 10 分钟通过审查

| Metric | Before | After | Change |
|---|---|---|---|
| 审查时间 | 120分钟 | 10分钟 | -92% |

## Readme

# idiomatic-zener

# Idiomatic Zener

Prescriptive style rules for `.zen` code. These apply to all modules, reference designs, and board files.

## No Conditional Instantiation

Never use `if` to create or remove components. Always instantiate every component. Use `dnp=` to control whether it is populated. This applies to modules, boards, and reference designs, including optional feature blocks.

```
# BAD
if add_decoupling:
    Capacitor(name="C_VDD", value="100nF", package="0402", P1=VCC, P2=GND)

# GOOD
Capacitor(name="C_VDD", value="100nF", package="0402", P1=VCC, P2=GND)

```

## DNP via Record Pattern

For optional subcircuits controlled by a config, use a record to pair values with DNP state. A zero/disabled config value means `dnp=True` with placeholder values.

```
Passive = record(value=typing.Any, dnp=bool)

input_filter = config("input_filter", Frequency, default="0Hz", optional=True,
    help="Input lowpass cutoff. 0Hz disables the filter.")

def input_rc(f):
    dnp = f <= Frequency("0Hz")
    r = e96(Resistance("100ohm") if not dnp else Resistance("0ohm"))
    c = e24(1 / (2 * PI * r * f) if not dnp else Capacitance("100pF"))
    return Passive(value=r, dnp=False), Passive(value=c, dnp=dnp)

input_r, input_c = input_rc(input_filter)
Resistor(name="R_IN", value=input_r.value, dnp=input_r.dnp, package="0402", P1=A, P2=B)
Capacitor(name="C_IN", value=input_c.value, dnp=input_c.dnp, package="0402", P1=B, P2=GND)

```

## Minimize Component Count

Fewer parts = simpler BOM, easier assembly, lower cost.

**Prefer value-switching over duplicate components.** When a config selects between discrete options, use a single component with a computed value — don't instantiate multiple components with opposing DNP conditions.

```
# BAD: two resistors, one always DNP
Resistor(name="R_STRAP_HI", value="10kohm", P1=STRAP, P2=VCC, dnp=mode != "HIGH")
Resistor(name="R_STRAP_LO", value="100kohm", P1=STRAP, P2=VCC, dnp=mode != "LOW")

# GOOD: one resistor, value changes with config
_strap_value = { Mode("HIGH"): "10kohm", Mode("LOW"): "100kohm", Mode("FLOAT"): "10kohm" }[mode]
Resistor(name="R_STRAP", value=_strap_value, P1=STRAP, P2=VCC, dnp=mode == Mode("FLOAT"))

```

**Leverage internal pull-ups/pull-downs.** Many ICs have internal bias on strap pins. If the default state uses the internal pull, don't add an external resistor — just DNP the single resistor for that case.

## Typed Unit Configs

Use physical types from `@stdlib/units.zen` for configs. Expose one meaningful parameter (e.g. cutoff frequency), not raw R/C values. Use `enum()` only for discrete design choices.

```
# BAD
config("filter_r", str, default="10ohms")

# GOOD
input_filter = config("input_filter", Frequency, default="0Hz", optional=True,
    help="Input lowpass cutoff. 0Hz disables the filter.")

```

## Computation in Named Functions

Put calculations in named functions with datasheet references. Snap to E-series with `e96()` / `e24()`.

```
def load_r(v_out, v_sense):
    """Datasheet §8.1.1 / Eq 4: V_OUT = V_SENSE × gm × R_L"""
    GM = Current("200uA") / Voltage("1V")
    return e96(v_out / (v_sense * GM))

```

## Voltage Checks on Power IOs

Every `Power` io gets `voltage_within` matching the datasheet's absolute maximum or recommended operating range.

```
VCC = io("VCC", Power, checks=voltage_within("2.7V to 36V"))

```

## Help Strings

Use `help=` when it adds integrator-visible meaning that is not already obvious from the name, type, checks, or default. Omit it when it would just restate those fields.

```
VDD = io("VDD", Power, checks=voltage_within("3.0V to 5.5V"))
GND = io("GND", Ground)
EN = io("EN", Net, help="High to enable the regulator")
input_filter = config("input_filter", Frequency, default="0Hz", optional=True,
    help="Input lowpass cutoff. 0Hz disables the filter.")

```

## No `.NET` Accessor

Use Power/Ground ios directly as pin connections. Never use `.NET`.

```
# BAD
Capacitor(name="C_VDD", value="100nF", P1=VCC.NET, P2=GND.NET)

# GOOD
Capacitor(name="C_VDD", value="100nF", P1=VCC, P2=GND)

```

## Naming

Beyond the standard conventions (UPPERCASE io, lowercase config):

Element
Convention
Example

Internal nets
`_` prefix
`_VREF`, `_XI`, `_RBIAS`

Component names
Uppercase functional prefix
`R_LOAD`, `C_VDD`, `U_LDO`

Differential pairs
`_P` / `_N` suffixes
`IN_P`, `IN_N` (not `_PLUS` / `_MINUS`)

## Opinionated Defaults

Don't expose configs for implementation details integrators shouldn't tune: decoupling cap values, passive package sizes, test point style.

Do expose configs for things integrators legitimately need to change: filter cutoffs, output voltage, gain settings, enable/disable optional subcircuits.

## Checklist

- No `if` guards on instantiation — always instantiate, use `dnp=`

- No `.NET` accessor — use ios directly

- No `str` configs for physical values — use typed units

- Calculations in named functions with `e96()` / `e24()`

- `voltage_within` on all `Power` ios

- Add `help=` only when it clarifies non-obvious integrator-facing meaning

- Diff pairs use `_P` / `_N`, not `_PLUS` / `_MINUS`

- Internal nets prefixed with `_`

- Minimize component count — value-switch, leverage internal bias

- When renaming components or nets, keep existing `# pcb:sch` comments in sync

Weekly Installs499Repository[diodeinc/pcb](https://github.com/diodeinc/pcb)GitHub Stars212First SeenMar 17, 2026Security Audits[Gen Agent Trust HubPass](/diodeinc/pcb/idiomatic-zener/security/agent-trust-hub)[SocketPass](/diodeinc/pcb/idiomatic-zener/security/socket)[SnykPass](/diodeinc/pcb/idiomatic-zener/security/snyk)Installed onclaude-code498opencode53gemini-cli53github-copilot53amp53cline53

---
*Source: https://skills.yangsir.net/skill/daily-idiomatic-zener*
*Markdown mirror: https://skills.yangsir.net/api/skill/daily-idiomatic-zener/markdown*