Skip to content

code-style.md

Latest commit

 

History

History
215 lines (155 loc) · 8.24 KB

code-style.md

File metadata and controls

215 lines (155 loc) · 8.24 KB

Code Style

Most code style rules are enforced automatically by the linter (ruff) and formatter (black + isort). See .ruff.toml for the full linter configuration. This document covers rules that tools cannot enforce.

Run: .\format_code.bat (formatter) | .\lint_code.bat all (linter)

Naming

Names must be descriptive and self-explanatory. Avoid vague names like _push, _do, _run_it. Name them for what they do: _push_settings_changed, _validate_host, _start_server.

Never use shorthand abbreviations. Spell out full words in all identifiers — variable names, style names, omni.ui style identifiers, constants, and class names.

Do Don't
InputRowBackground InputRowBg
_section_header _sec_hdr
Button Btn
Separator Sep
_selected_index _sel_idx
workflow_input inp

This applies everywhere: variables, parameters, loop variables, and comprehension variables.

omni.ui Layout Rules

See docs_dev/patterns/ui-style.md for all omni.ui layout rules including:

  • Layout constants (class-level ui.Pixel definitions)
  • Layout spacing (no style={} — use stacks + spacers)
  • Background patterns (ZStack + Rectangle)
  • Tree widget patterns

Class Member Ordering

Order members by visibility.

  1. Dunder methods (__init__, __call__, __del__, etc.)
  2. Public properties
  3. Protected properties
  4. Public methods
  5. Protected methods (_-prefixed)
  6. Private methods (__-prefixed)

Exceptions: Related members may be grouped together when it aids readability:

  • A public property and its setter can sit next to each other.
  • A public method and its corresponding protected/private helper can sit next to each other.

Use the ordering above as the default; only deviate when keeping related pairs together makes the code easier to follow.

Module Exports

__all__ must be defined in every public module and every __init__.py. All imports in __init__.py files must be listed in __all__. Never use the import X as X pattern to suppress F401 lint warnings — __all__ is the correct mechanism.

# Good
__all__ = ["Foo", "Bar"]

from .foo import Foo
from .bar import Bar

# Bad — never do this
from .foo import Foo as Foo
from .bar import Bar as Bar

Imports

isort Grouping

Treat carb, omni, and lightspeed as third-party. The formatter handles sorting automatically — see .ruff.toml for the full isort configuration.

For import rules that affect correctness and architecture (symbol imports, relative vs absolute), see engineering-standards.md → Import Rules.

Import Aliases

Avoid import aliases (import x as y or from x import y as z) unless there is a name collision or a widely established external convention. Prefer real module and symbol names so patch targets, stack traces, and grep results stay obvious.

License Headers

Every Python source file must begin with an SPDX Apache-2.0 license header as its first docstring.

"""
* SPDX-FileCopyrightText: Copyright (c) <YEAR> NVIDIA CORPORATION & AFFILIATES. All rights reserved.
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
"""
Scenario Action
New files Use the current year
Existing files Do not change the year
Existing files missing the header Add it. Use git log --follow --diff-filter=A -- <file> to find the original year
Non-Python files (.toml, .lua, .md, .rst, .kit) No header required

omni.ui Color Format

Colors in omni.ui and trex_style.py use AABBGGRR byte order (NOT AARRGGBB). This is because omni.ui uses ImGui's color format internally.

# Example: 50% transparent white
_WHITE_50 = 0x80FFFFFF   # AA=0x80, BB=0xFF, GG=0xFF, RR=0xFF

# Example: opaque NVIDIA green (#76B900)
_NV_GREEN = 0xFF00B976   # AA=0xFF, BB=0x00, GG=0xB9, RR=0x76
#                                    ^^     ^^     ^^
#                                    B      G      R   (reversed from HTML #RRGGBB)

When converting from web/HTML hex colors (#RRGGBB), reverse the R/G/B bytes and prepend the alpha byte.

Inline Comments

Only comment the why, never the what. If a comment explains what the code does, rewrite the code to speak for itself.

Do Don't
Non-obvious design constraints Narrating obvious steps (# Create the widget)
Invariants not enforced by types Development history (# Tried X, so we do Z)
Debugging breadcrumbs

Prefer code that doesn't need comments: rename variables, add type hints, extract well-named helpers.

Docstrings (Google Style)

All public and protected members require a docstring. Only name-mangled private members (__foo) can omit one unless the logic is non-obvious.

Functions and Methods

def process_textures(paths: list[str], output_dir: str, overwrite: bool = False) -> list[str]:
    """Convert source textures to the Remix-compatible format.

    Skips files that already exist in output_dir unless overwrite is set.

    Args:
        paths: Absolute paths to source texture files.
        output_dir: Directory where converted textures are written.
        overwrite: If True, re-convert files that already exist. Defaults to False.

    Returns:
        Absolute paths of all successfully converted output files.

    Raises:
        FileNotFoundError: If output_dir does not exist.
        ValueError: If paths is empty.
    """
Rule Detail
Summary line One sentence, ending with a period
Args Describe the meaning, not the type (it's in the signature)
Returns / Raises Only if meaningful beyond the type annotation
Self-explanatory signatures A one-line summary is sufficient

Classes

class TextureConverter:
    """Converts game textures to Remix-compatible formats.

    Maintains a session-level cache of already-converted paths to avoid
    redundant work across multiple calls. Not thread-safe — create one
    instance per job.

    Attributes:
        output_dir: Root directory where converted textures are written.
    """
Rule Detail
Focus Role and contract, not implementation
Constraints Call out thread safety, lifetime, ownership
Attributes List public attributes not obvious from __init__

Modules

Top-level module docstrings are optional but useful for .core and .service extensions. Keep to 1-3 sentences.