Style & Best Practices

5 min read · Beginner

You will learn

Naming conventions that stay readable six months later
How to organise large files with sections and comments
A professional style checklist to apply to every file

Just like keeping your desk organized helps you work better, following good practices with YAML will make your files easier to read, share, and maintain. Let’s learn some simple habits that will make you look like a pro!

Rule 1: Use Clear and Descriptive Names

Choose names that clearly explain what something is or does.

Good examples:

# Easy to understand names

processor_speed_mhz: 100

memory_size_mb: 512

power_consumption_watts: 2.5

designer_name: "Alice Johnson"

project_start_date: "2024-01-15"

Poor examples (don’t do this):

# Hard to understand names

ps: 100 # What is "ps"?

ms: 512 # Memory size? Milliseconds?

pc: 2.5 # Power consumption? Personal computer?

dn: "Alice" # Designer name? Directory name?

The good names include the unit in the name (_mhz, _mb, _watts). This makes the file self-documenting — anyone can understand it without a separate manual.

Rule 2: Use Consistent Naming Conventions

Pick a naming style and stick with it throughout your project:

snake_case (recommended for YAML):

processor_config:
  clock_frequency_mhz: 400
  power_consumption_mw: 150
  cache_size_kb: 64

Pick one style and use it everywhere! Mixing processorConfig with power_consumption in the same file is confusing.

Rule 3: Document Your Files

Add a header block at the top of every configuration file, and use comments to explain each section:

# =================================================================

# Semiconductor Design Configuration File

# Project: Next-Gen Processor Core

# Author: Design Team

# Last Updated: 2024-01-15

# =================================================================

# Technology specifications

technology_node:

·· process: "5nm FinFET" # Manufacturing process

·· foundry: "TSMC" # Semiconductor foundry

·· metal_layers: 15 # Number of metal layers

# Design constraints and requirements

constraints:

·· performance:

···· max_frequency_ghz: 3.2 # Maximum operating frequency

···· ipc_target: 4.5 # Instructions per cycle target

·· power:

···· max_tdp_watts: 95 # Thermal design power

···· idle_power_watts: 5 # Power in idle state

· = one space

Good documentation includes:

A header block with project name, author, and last updated date
Section comments explaining what each group is for
Inline comments explaining individual values and their units

Rule 4: Organize Information Logically

Group related settings together and separate groups with blank lines:

# Project Information
project:
  name: "5G Baseband Processor"
  version: "2.1"
  team: "RF Design Team"

# Hardware Specifications  
hardware:
  processor:
    architecture: "ARM"
    cores: 8
    frequency_ghz: 2.4

# Power and Thermal
constraints:
  max_power_w: 25
  supply_voltage_v: 0.8

Key takeaways

Following best practices ensures maintainable and robust YAML configurations:

✓ Use descriptive names with units (frequency_mhz, not f)
✓ Use consistent naming — snake_case throughout
✓ Document your files — header block + section comments + inline comments
✓ Organize logically — group related settings, separate with blank lines
✓ Include units in key names so values are self-documenting

Congratulations — you now know how to read, write, and maintain professional YAML configuration files for semiconductor design. One step remains: learning how Python scripts consume these files so you can close the loop between your config and the tools that use it.

← Previous Next: Optional · Automation with Python →