# ML Frameworks & Platforms Training and inference frameworks, tensor and kernel code, ML platforms and pipelines. 343 instructions from 14 repositories. Last updated 2026-04-28. --- ## Keep config minimal Avoid “config monsters” by limiting new runtime knobs and centralizing stable defaults. Only add CLI/config parameters when they materially change behavior across experiments; otherwise, bake them into the existing config (or the run script) and reuse current config locations rather than introducing new config modules for a few constants. For evaluation-critical settings, explicitly pin values and avoid hidden coupling between constants. Apply: - Don’t add dozens of flags for one model variant—prefer a single enabling flag (or none) with fixed defaults baked into config. - Reuse existing config files/modules; if you need only a few constants, place them alongside the code that consumes them instead of adding a new Python module. - Pin eval constants explicitly (e.g., `VAL_SHARD_INDEX = 1822`) rather than tying them indirectly to other values that might change. - At configuration boundaries (CLI), constrain allowed values (e.g., `choices`) so invalid settings fail fast. Example (CLI boundary + baked/stable defaults): ```python import argparse parser = argparse.ArgumentParser() parser.add_argument('--device', type=str, default='cuda', choices=['mps','cuda']) # Keep eval config explicit and stable VAL_SHARD_INDEX = 1822 ``` --- ## PyTorch Compatibility Guards Adopt explicit compatibility guards in PyTorch code to prevent silent numeric issues and runtime failures across devices, PyTorch versions, and compilation modes. Apply these rules: - Explicitly initialize newly introduced parameters/buffers (don’t rely on defaults). - Feature-detect PyTorch APIs and provide fallbacks for older versions. - Avoid backend-incompatible tensor ops (e.g., MPS limitations). Use safer construction paths or backend-specific branches. - If you dynamically grow/update caches/buffers (e.g., RoPE cos/sin), do it lazily, preserve dtype/device, overwrite existing buffers without re-registering names, and guard against mutation during `torch.compile` tracing. Example pattern (combine the above): ```python import torch import torch.nn.functional as F # 1) Explicit init # self.smear_lambda is a Parameter or buffer newly added # Always initialize deterministically. torch.nn.init.zeros_(self.smear_lambda) # 2) Version/API fallback def norm(x): if hasattr(F, "rms_norm"): return F.rms_norm(x, (x.size(-1),)) # fallback implementation (placeholder) return x * 1.0 # 3) Safe dynamic cache update with compile guard def ensure_rope_cache(model, needed_seq_len: int, device: torch.device): cur_len = model.cos.size(1) if needed_seq_len <= cur_len: return try: import torch._dynamo if torch._dynamo.is_compiling(): raise RuntimeError("RoPE cache growth during torch.compile is unsafe; pre-size or disable compile.") except Exception: pass new_len = 1 << (needed_seq_len - 1).bit_length() head_dim = model.config.n_embd // model.config.n_head cos, sin = model._precompute_rotary_embeddings(seq_len=new_len, head_dim=head_dim, device=device) # preserve invariants and overwrite existing registered tensors cos = cos.to(dtype=model.cos.dtype, device=device) sin = sin.to(dtype=model.sin.dtype, device=device) model.cos = cos model.sin = sin ``` This standard reduces runtime surprises (especially on MPS), keeps numerics stable when adding parameters, and prevents compilation/tracing issues when using dynamic tensor caches. --- ## Use exact math semantics When implementing performance-critical algorithms (e.g., pooling, math kernels, SIMD/ISA code), preserve the algorithm’s true numeric semantics and parameterization: 1) Match rounding/truncation semantics with the ISA’s exact instruction - Prefer the native intrinsic that implements the intended operation (e.g., truncation toward zero) rather than approximating via integer conversion that may differ. - Example (aarch64): ```cpp static inline float32x4_t trunc_ps(const float32x4_t& x) { #if __aarch64__ return vrndq_f32(x); // trunc toward zero #else // fallback, but verify it matches trunc-toward-zero semantics int32x4_t xi = vcvtq_s32_f32(x); return vcvtq_f32_s32(xi); #endif } ``` 2) Don’t “constant-fold” parameters that are mathematically location-dependent - If kernel extents (or other algorithm parameters) vary per output position, compute them per position in the same execution space (shader/CPU) or pass the per-position values explicitly. - For adaptive pooling: kernel_w/kernel_h generally depend on gx/gy (output location), so computing a single constant kernel on CPU and reusing it is incorrect. Keep the dynamic computation consistent with the reference definitions. 3) Add a quick correctness checklist during review - Numeric ops: confirm rounding direction (floor/ceil/trunc) and tie behavior where relevant. - Parameter definition: confirm which variables are constant vs per-location/per-channel. - Kernel wiring: verify parameter order (e.g., bias vs kernel) to avoid silent swaps that still compile. Applying this standard prevents cross-architecture drift (wrong rounding) and algorithm drift (wrong kernel sizes), which are frequent root causes of subtle accuracy regressions in algorithmic code paths. --- ## Deterministic selection parsing When implementing algorithmic “pick/keep/max” logic, make the selected set deterministic and the ordering explicit—then compute sort/max keys using robust parsing. Apply: - Filter at the source: if a category (e.g., val shard) must never be in a selection, exclude it during construction rather than appending then removing. - Avoid redundant de-dup/sort: if the list you start with (e.g., `range(n)`) is already unique and ordered, don’t add `set()` or extra `sorted()` just to satisfy uniqueness. - Use reliable key extraction for maxima: prefer `Path`/`stem`/`name` and direct `stat().st_mtime` for sort keys; keep parsing aligned with how files are named/saved. Example (ids construction and checkpoint step selection): ```python # Deterministic, minimal ordering ids_to_download = list(range(num)) if VAL_SHARD_INDEX not in ids_to_download: ids_to_download.append(VAL_SHARD_INDEX) ids_to_download.sort() # only if you must re-establish order # Robust parsing + max selection checkpoint_files = list(checkpoint_dir.glob('model_*.pt')) last_step = int(max(f.stem.split('_')[-1] for f in checkpoint_files)) ``` --- ## Guard and narrow exceptions When an operation can fail in a known way (edge-case inputs, risky math, I/O/parsing, optional capabilities), handle it explicitly: - Add targeted guards before risky computations (e.g., avoid dividing/normalizing by an empty denominator). - Use narrow exception handling for the *actual* API you call (don’t add `except Exception` that unintentionally swallows the error you meant to surface). - On failure, clean up partial/corrupted artifacts so the next run can retry, and prefer graceful recovery (skip/continue, warn+cap) when continuing is safe. Example (defensive guard + clean recovery): ```python num_tokens = torch.tensor(0, device=device) steps = [next(train_loader) for _ in range(grad_accum_steps)] num_tokens += sum((targets >= 0).sum() for _, targets in steps) # (optional) sync across ranks if ddp: dist.all_reduce(num_tokens, op=dist.ReduceOp.SUM) # prevent NaN loss if num_tokens.item() == 0: model.zero_grad(set_to_none=True) # skip this accumulation window return for train_inputs, train_targets in steps: loss = model(train_inputs, train_targets, loss_reduction='sum') loss = loss / num_tokens loss.backward() ``` Example (don’t swallow intended errors): ```python # WRONG: throws, then immediately swallows everything try: raise RuntimeError("something important") except Exception: pass # RIGHT: either remove the throw/silencing, or narrow the exception try: import torch._dynamo if torch._dynamo.is_compiling(): raise RuntimeError("RoPE cache too small during torch.compile") except ImportError: # only ignore the missing module case pass ``` Example (cleanup on integrity failure): - If checksum verification fails, delete the bad file (and optionally the temp file), then retry or fail cleanly—don’t leave a corrupt artifact that prevents future re-download/re-verify. Apply this consistently across training loops, dataset download/verification, and state load paths. --- ## Idiomatic Readable Formatting When touching code that formats output or builds paths, keep it idiomatic and repo-consistent: - Avoid inline conditionals inside large f-strings; precompute conditional fragments and interpolate them. - If the value is already a `Path`, build derived paths with `Path` operators (`base / name`, `with_name`) instead of `os.path.join`. - Don’t add redundant casts/conversions (e.g., `int(round(x))` when `round(x)` already returns an `int`). - Add/remove type annotations consistently with the repo’s style (don’t introduce isolated type hints that the rest of the file/project doesn’t follow). Example (readable conditional print): ```python print_grad_norm = "" if grad_clip > 0.0: print_grad_norm = f"grad_norm: {grad_norm.item():.5f} | " print0( f"step {step:05d}/{num_iterations:05d} ({pct_done:.2f}%) | " f"loss: {debiased_smooth_loss:.6f} | " f"{print_grad_norm}" f"lrm: {lrm:.2f} | dt: {dt * 1000:.2f}ms | tok/sec: {tok_per_sec:,} | " f"mfu: {mfu:.2f} | total time: {total_training_time/60:.2f}m" ) ``` Example (Path composition): ```python checkpoints_dir = base_dir / model_dir # when base_dir is a Path lock_path = file_path.with_name(f"{file_path.name}.lock") ``` --- ## Capability-Aware Fast Paths When optimizing for speed, make the fast path both *correct for the actual hardware* and *lightweight in implementation*. 1) Keep kernel support documentation accurate and capability-aware - Maintain an explicit GPU architecture support matrix for optimized kernels. - Only claim “Hopper-only” (or similar) if that’s true; otherwise document the actual compiled architectures. - Ensure the code selects an appropriate fallback (e.g., SDPA) for unsupported architectures. Example (pattern): ```python # Supported FA3 archs reflect what kernels are compiled for # sm90 (Hopper), sm89 (Ada), sm80/sm86 (Ampere) # sm100 (Blackwell): fallback to SDPA until FA3 is recompiled def _load_flash_attention_3(): if not torch.cuda.is_available(): return None # ... select FA3 vs fallback based on device capability ... ``` 2) Avoid unnecessary overhead in parsing/utility code - If checkpoint filenames are already guaranteed to match `model_.pt`, prefer simple `split`/string ops over regex. - Remove extra path manipulation (`basename`) when you already operate on plain filenames. Example (pattern): ```python # checkpoint_files contains only filenames like model_123456.pt last_step = int(max(f.split("_")[-1].split(".")[0] for f in checkpoint_files)) ``` Result: faster execution with fewer CPU-side bottlenecks, and fewer correctness surprises caused by stale/incorrect hardware assumptions. --- ## Deterministic CI Runs Ensure GitHub Actions CI runs are repeatable, targeted, and don’t rely on brittle hacks. 1) Run tests using the environment you just prepared - If you use `uv sync`, run pytest using the created venv/python (or otherwise guarantee `uv run` uses the synced environment without re-installing). - Keep platform-specific dependency workarounds explicit (e.g., CPU-only torch on runners without CUDA). 2) Install the project instead of mutating PYTHONPATH - Prefer editable installs so imports behave the same as in real usage. - Example: ```yaml - name: Set up uv uses: astral-sh/setup-uv@v7 - name: Install dependencies run: | uv sync --extra cpu uv pip install -e . # CPU-only torch for Linux runners without CUDA uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu - name: Run tests run: | .venv/bin/pytest tests/ ``` 3) Keep workflows minimal and aligned with support - Restrict `on.push` to `master/main` (and use `pull_request` for PR validation) rather than running on every branch push. - Keep OS/Python matrices to versions you truly support; avoid redundant `if:` conditions for OSes not in the matrix. - Use consistent, up-to-date versions of actions/tools and avoid redundant installs when the action already provides them. Applying this prevents CI flakiness from environment mismatches, reduces “works on my machine” import issues, and cuts unnecessary CI load. --- ## Consistency And Readability Apply a single, repeatable style checklist across all new/modified code: 1) Remove unused/redundant code - Drop unused `#include`s and unused variables. - Don’t add overrides or plumbing that the base class already provides (avoid “override without purpose”). - Keep diffs focused: avoid unrelated call-site churn when a helper can encapsulate logic. 2) Keep compiler/standard compatibility - Don’t use C++11-only syntax where the project targets older compilers/standards (e.g., avoid `{...}` initializer lists). - Avoid range-based `for` if the codebase/toolchain constraints require explicit indexing. - For const objects, ensure initialization is explicitly safe for older clangs (prefer `const T t = {};` over uninitialized default construction). 3) Factor preprocessor/SIMD-heavy logic for readability - When you have long `#if/#ifdef` blocks for SSE/AVX/AVX512, move the implementation into small helper functions (e.g., `packA_*`, `packB_*`, `subkernel_*`) so the main algorithm focuses on tiling/control flow. 4) Enforce formatting conventions - Use consistent comment formatting (UTF-8, `// comment` with a space; keep meaningful text aligned with code). - Prefer correct preprocessor directives (`#if` vs `#ifdef`) and consistent patterns. - Handle unused parameters cleanly (e.g., `(void)opt;`). Example (SIMD factoring) ```cpp static void packA_sse(const float* src, float* dst, int k, const Option& opt); static void packA_avx(const float* src, float* dst, int k, const Option& opt); for (int i = 0; i < M; i += TILE_M) { // keep tiling/control logic here if (j == 0) { #if __SSE2__ #if __AVX__ packA_avx(A_ptr, AT_ptr, k, opt); #else packA_sse(A_ptr, AT_ptr, k, opt); #endif #endif } } ``` --- ## Use clear names Rule: choose concise, semantically accurate, and responsibility-respecting names for identifiers (variables, functions, classes, modules). Motivation: clear names reduce cognitive load, avoid ambiguity, and prevent leaking responsibilities across layers. Guidelines: - Prefer concise domain nouns; drop redundant suffixes or qualifiers. Example: use tagger (not tagger_plugin), directory name taggers (not taggers_plugin). For classes, avoid duplicative internal fields like _categorical when the class name already communicates the type. - Bad: tagger_plugin: str - Good: tagger: str - Make names reflect their return type/semantics. Use verbs for actions and nouns for data; name boolean flags clearly. Examples: - get_trials_completed() -> count_completed_trials() # returns int - get_* should return objects or collections; count_/is_/has_ for predicates or numeric counts. - For binary options prefer a boolean with a neutral name rather than a Literal with two labels. Example: - mode: Literal["remove_inhibitions","increase_inhibitions"] -> reverse: bool = False - Express units and domains in names. If a value is a fraction (0..1), name it accordingly. Example: - winsorization_level (0..100) -> winsorization_quantile (0.0..1.0) - Do not embed UI/label or management concerns inside low-level classes. E.g., avoid passing instance_name or display labels into classes that represent logic; labeling/aggregation belongs to higher-level code. - Bad: Scorer(..., instance_name=...) - Good: keep Scorer focused on behavior; management code assigns names/labels. - Flatten and standardize config types for plugins. Prefer a nested Settings model named Settings or a top-level Settings type over nonstandard nested names like PluginSettings. This keeps plugin initialization consistent. - Bad: class KLDivergence(Scorer): class PluginSettings(BaseModel): ... - Good: class KLDivergence(Scorer): class Settings(BaseModel): ... or unnest to module-level Settings. - Keep internal naming consistent; map to user-facing labels only at presentation boundaries. If internal code uses scores, stick with scores; render them as "Metrics" only in displays. Code examples: - Rename and semantics: - Before: study_name = "heretic_study_" + "_".join(study_components) - After: study_name = "_".join(study_components) # omit unnecessary prefix - Function naming: - Before: def get_trials_completed() -> int: ... - After: def count_completed_trials() -> int: ... Application checklist for reviewers: 1. Ask: Is any word redundant given the type or context? Remove it. (e.g., _plugin, _categorical) 2. Ask: Does the name indicate the value’s type/unit/semantics? If not, clarify (e.g., _quantile, is_*, count_*). 3. Ask: Is responsibility leaking into this identifier? Move UI/label/instance concerns out of logical classes. 4. Verify consistency across modules (e.g., scores vs metrics) and pick a single internal term. References: discussion indices [0,1,3,4,6,7,8,10,11,12,13]. --- ## Configuration ownership and determinism Summary - Ensure configuration is explicit, owned by the correct component (application vs plugin), and deterministic so behavior is predictable and resumable. Why this matters - Mixing app-level Settings with plugin internal defaults or duplicating metadata produces inconsistencies and surprises for users (e.g. tagger metadata, plugin defaults). - Silent, environment-specific changes (dtype/device heuristics, implicit reordering of dtypes, magic numbers like LoRA rank) make runs non-reproducible and hard to debug. - Study resume/checkpointing requires deterministic serialization of the settings that actually affect results. How to apply (concrete rules) 1) Ownership — plugin-provided defaults and metadata - Plugins must declare their own config schema and provide defaults/metadata. The application Settings should not duplicate plugin internals. - Example pattern (plugin exposes defaults): class MyPluginSettings(BaseModel): markers: list[str] class MyPlugin: @classmethod def default_settings(cls) -> MyPluginSettings: return MyPluginSettings(markers=["I refuse", "sorry"]) - At load time the app merges user settings with the plugin defaults returned by the plugin, rather than embedding plugin defaults into global Settings. 2) Deterministic checkpointing and resume - Serialize the exact Settings that determine study behavior deterministically (sorted keys) and store that serialization alongside any checkpoint/log file. Use that serialized object to compute a resume hash. - Example (deterministic JSON hash): import json, hashlib serialized = json.dumps(settings.model_dump(exclude_none=True), sort_keys=True) settings_hash = hashlib.sha256(serialized.encode('utf-8')).hexdigest() - Save the serialized settings in study metadata (or the checkpoint file) so resume can verify compatibility and users can inspect what was used. - Make checkpoint directory/name configurable; provide a sensible auto-derived default (e.g. include model name and timestamp) for usability. 3) Explicit, scoped configuration for non-obvious choices - Surface any "magic numbers" or heuristics as explicit, well-named config fields. Scope names to the feature where they apply to avoid misleading global settings (e.g. full_normalization_lora_rank = 3). - Document when defaults apply (e.g. "only used when row_normalization == 'full'"). 4) Avoid silent platform/environment heuristics - Do not silently override user-specified config (e.g., reorder dtypes or change dtype cascade) unless the user opts in. If heuristics are necessary, make them opt-in and clearly logged. - If you must handle platform quirks, document the rule and confine it to a small, explicit code path with a clear config flag. 5) Structured config types and robust parsing - Use explicit dataclasses/Pydantic models and enums with validators for plugin and app configs. This avoids type/persistence surprises (e.g., enum -> int when restoring) and allows validation. - Example: use a Pydantic model with @field_validator to parse legacy values. 6) Precedence and sources - Define and document settings precedence (CLI vs stored settings vs env vs defaults). When resuming from a stored Settings object, consider treating the stored settings as authoritative for reproducibility; allow intentional overrides but require explicit user action. 7) Prefer maintained utilities over ad-hoc checks - Reuse tested utilities from dependencies (e.g. reusing rich/_is_jupyter for notebook detection) instead of multiple fragile heuristics. Checklist for code reviewers - Does each plugin expose its own settings and defaults? (avoid embedding plugin defaults into global config) - Are magic numbers surfaced as scoped config fields with clear names and docs? - Is checkpoint/ resume hashing based on deterministic serialization of the relevant Settings, and is the serialized settings stored with the checkpoint? Is the checkpoint dir/name configurable? - Are any platform-specific heuristics documented and opt-in? Are silent overrides avoided? - Are config types structured (dataclass/Pydantic/Enum) and do they include validators to handle persistence or legacy values? Applying these rules will reduce configuration drift, improve reproducibility (especially for resumable experiments), and make the system easier to understand and extend by ensuring clear ownership and deterministic behavior. --- ## Model integration rules When adding or changing model loading, quantization, LoRA/abliteration logic, or merging behavior, follow these explicit rules to ensure correctness, compatibility and reproducibility. 1) Explicit quantization and dtype handling - Provide a single helper that builds BitsAndBytesConfig from settings and the chosen dtype. For 4-bit require an explicit compute dtype (e.g., torch.bfloat16) and document why (bnb dequantizes to compute_dtype each forward). - Print clear messages when a model is loaded in 4/8-bit and when compute_dtype is chosen. - Keep a documented dtype cascade (e.g., ["auto","float16","bfloat16","float32"]) and explain fallback rationale in code comments. Example: quant_cfg = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.bfloat16, ...) 2) LoRA adapter configuration and scaling - Store/reuse a single peft_config object rather than duplicating LoRA construction logic. - If you compute target weight deltas directly (instead of training), set lora_alpha == r to avoid extra scaling: lora_alpha must equal LoRA rank so alpha/r == 1. - Initialize PEFT with explicit targets (leaf names) and document that extra adapters on unrelated modules are harmless if unused. 3) Row normalization / magnitude preservation modes - Expose an enum (NONE/PRE/FULL) and implement each mode explicitly: - PRE: apply row norms to LoRA_B so adapters act on original W - FULL: apply update, normalize rows, restore original row norms, compute delta, then extract low-rank approximation via svd_lowrank - NONE: apply low-rank update directly - When forming LoRA components from SVD, balance singular values across A and B for numerical stability (e.g., use sqrt(S) into both sides) and document why. Snippet (FULL flow outline): W = W_org.view(W.shape[0], -1) W = W + lora_B @ lora_A W = F.normalize(W, p=2, dim=1) W = W * W_row_norms W = W - W_org U, S, Vh = torch.svd_lowrank(W, q=2*r+4) # split sqrt(S) across U and V lora_B = U[:, :r] @ diag(sqrt_S) lora_A = diag(sqrt_S) @ Vh[:r, :] 4) Compatibility & hybrid fallback - When inspecting model layers, unwrap PeftModel (e.g., model.base_model.model) to find language layers. - Use a hybrid path: if a module has LoRA adapters (hasattr(module, 'lora_A')), perform LoRA-based abliteration; otherwise fall back to direct weight modification on nn.Parameter tensors. This ensures support for non-standard implementations (e.g., GPT-OSS) without breaking standard models. - Flatten weight matrices for conv/4D tensors to (out_features, in_features) when constructing LoRA components, so LoRA storage matches PEFT expectations. 5) Safe merging for quantized models - Before merging adapters into a quantized model, copy adapter parameters to CPU: adapter_state = {name: param.data.clone().cpu() for name, param in peft_model.named_parameters() if 'lora_' in name} - Reload base model on CPU (device_map='cpu', appropriate torch_dtype), create a peft wrapper with the same peft_config, copy adapter_state into it, then call merge_and_unload() on that CPU model. Warn users about memory usage and provide an "adapter-only" save option. - After merge_and_unload, mark that the running process may need a full reload if further LoRA operations are expected. 6) Data processing and diagnostics - Implement winsorization/clamping per-layer (and per-prompt if desired) but document axes and intent clearly. Add explanatory comments in code about the chosen axis. - Avoid redundant safety guards that mask underlying bugs (e.g., negative KL indicates a calculation bug and should not be silently clamped). 7) UX, tests, and diagnostics - Prompt users clearly when requiring trust_remote_code; set trusted_models[model] only after a successful load that required confirmation. - Enumerate all detected devices (GPU count and names) for clearer logs. - Use small toy models in unit/CI tests to avoid large downloads and flakiness. Why this matters (motivation) - Generative AI stacks mix many moving parts: quantization, PEFT/LoRA, architecture variations (modules vs raw parameters), and numerical normalization. Making integration rules explicit prevents subtle bugs (incorrect scaling, broken merges, unsupported layers), ensures reproducible experiments, and avoids user/system-level failures (OOM during CPU merges). References: discussions about LoRA scaling, normalization and merging, quantization config and compute dtype, hybrid compatibility and PEFT unwrapping, winsorization axis and testing guidance (see source discussions). --- ## Safe configuration defaults When writing run/config scripts, prefer *local, opt-in* environment changes and *guarded* defaults. **Rules** 1. **Don’t mutate persistent user config** (e.g., appending to `~/.bashrc`/`~/.profile`). If you need PATH changes, set them for the current process only (e.g., `export PATH=...` inside the script). 2. **Avoid forcing hardware/stack overrides by default.** Hardware-specific env vars (like ROCm/GFX overrides) should be enabled only when explicitly requested or when you can confidently detect the target GPU. 3. **Install system dependencies only when required, and only after detection.** If a dependency is needed (e.g., headers for compilation), detect its presence and install conditionally; keep messaging clear so it’s obvious why the install happened. **Example pattern** ```bash #!/usr/bin/env bash set -euo pipefail # Local PATH change (no ~/.bashrc mutation) if command -v uv &>/dev/null; then :; else curl -LsSf https://astral.sh/uv/install.sh | sh fi export PATH="$HOME/.local/bin:$PATH" # Conditional system dependency (only if missing) if ! dpkg -s python3-dev &>/dev/null; then echo "Installing python3-dev (needed for Python.h during compilation)" sudo apt-get update && sudo apt-get install -y python3-dev fi # Hardware override: opt-in via env var # e.g. export HSA_OVERRIDE_GFX_VERSION=11.0.0 before running if needed : "${HSA_OVERRIDE_GFX_VERSION:=}" if [ -n "${HSA_OVERRIDE_GFX_VERSION}" ]; then export HSA_OVERRIDE_GFX_VERSION fi exec python3 -m your_program "$@" ``` Applying this standard reduces cross-environment breakage (VM/container/bare metal), prevents unintended side effects on developers’ shells, and avoids configuration values that can harm unsupported hardware. --- ## Manage tensors proactively Motivation: Large models and matrix ops can produce big ephemeral tensors, cross-device copies, and temporary allocations that lead to excessive memory use or OOMs. Adopt consistent, device-aware tensor handling, prefer built-in ops, and free large temporaries at clear boundaries. Guidelines: - Avoid unnecessary copies: use Tensor.to(dtype, copy=True) when you need a guaranteed new tensor; skip copying if you don't perform in-place mutation. Example: W = base_weight.to(torch.float32, copy=True) # only if you will modify W in-place - Use built-in numeric primitives where possible (F.normalize, torch.linalg.vector_norm, etc.) instead of brittle manual clamps. Prefer out= variants if you truly need to avoid temporaries. Example: F.normalize(W, p=2, dim=1, out=W) # in-place normalization to save allocs when safe - Be device-aware: move small helpers to the target tensor's device before heavy ops to avoid implicit cross-device copies. Example: device_projector = projector.to(matrix.device) matrix.sub_(weight * (device_projector @ matrix)) - Free large temporaries at well-defined lifecycle boundaries (model reload, merge/save, end of trial). If you observe OOMs or large resident memory, explicitly delete big objects and force collection: Example: del merged_model import gc, torch gc.collect() torch.cuda.empty_cache() Use these only at boundaries where large tensors are no longer needed; don't sprinkle gc.collect() indiscriminately. - Profile expensive steps (e.g., low-rank SVD) before tuning: measure runtime and only reduce accuracy parameters (q, niter, rank) if they meaningfully affect end-to-end time/quality. When to use which pattern: - Small temporary adjustments and pure computations: prefer out-of-place safe ops and avoid premature gc. - Large model merges, reloads, or per-trial bulk computations: delete large objects promptly and call gc.collect() + torch.cuda.empty_cache() on memory-constrained systems. Result: following these practices reduces peak/resident memory, avoids hidden cross-device allocations, and keeps heavy numeric code both readable and efficient. --- ## plugin contract API Define a clear, minimal plugin contract and loader API for all external/ built-in plugins. Motivation: plugins (taggers/scorers) are the public extension points of the system and must declare what data they need, how they initialize, and be loadable from arbitrary modules so users can provide custom implementations without modifying the project. Rules and how to apply them: - Declarative requirements: each plugin class must provide classmethods that declare required fields. Example methods: required_response_metadata_fields() -> list[str], required_context_metadata_fields() -> list[str]. The core app will call these before invoking the plugin and instruct the Model to only return requested fields. - Optional heavy fields: plugins must indicate whether they need the full response text or only a prefix/n tokens. Make this configurable so the model can avoid returning expensive data when unnecessary (e.g., include_text() -> bool or text_token_limit() -> int). - Settings schema: plugins may declare a pydantic BaseModel subclass as `settings` to validate plugin-specific configuration. The loader should instantiate plugin settings from the global config. - Lifecycle hooks and validation: enforce a small lifecycle surface. Plugins must not define __init__(); instead provide an init(ctx) -> None hook for initialization and an optional start(ctx) for runtime setup. Provide a validate_contract() classmethod that the loader calls to enforce these rules and raise clear errors. - Loader API: implement a loader that accepts both built-in names and arbitrary module paths (e.g., "heretic.taggers.builtin", "~/my_plugins/custom_tagger.py:MyTagger", or "package.module:ClassName"). The loader must: - resolve either a package-qualified plugin or a file/module path - import and locate the plugin class - call plugin.validate_contract() - read plugin.required_* methods and configure the Model/Context accordingly (e.g., model.set_requested_response_fields(...)) - instantiate the plugin with the canonical constructor arguments (settings, model/context, etc.) - Keep APIs minimal and consistent: plugin methods should accept explicit typed objects, not ad-hoc arg lists. Use small domain objects like Response and Context rather than multiple parallel arguments. Example Response: Response(text: str | None, metadata: dict[str, Any], tokens: Optional[list[int]]). Make fields optional and typed so callers know what's available. Example usage (illustrative): # Plugin class (sketch) class MyTagger(TaggerBase): @classmethod def required_response_metadata_fields(cls) -> list[str]: return ["logprobs", "finish_reason"] @classmethod def include_text(cls) -> bool: return False # avoids returning full text when not needed @classmethod def validate_contract(cls) -> None: # ensure no __init__ and required methods exist ... def init(self, ctx: Context) -> None: # optional initialization using provided Context ... def tag_batch(self, responses: list[Response]) -> list[dict[str, float]]: ... # Loader usage (sketch) plugin_cls = load_plugin(name=settings.tagger) # accepts package name or module:path plugin_cls.validate_contract() model.set_requested_response_fields(plugin_cls.required_response_metadata_fields()) model.set_requested_context_fields(plugin_cls.required_context_metadata_fields()) plugin = plugin_cls(settings=settings, model=model, context_metadata=model.get_context_metadata()) plugin.init(Context(settings=settings, model=model)) Rationale: This rule prevents fragile implicit contracts, avoids unnecessary data transfers (performance), enables third-party plugin distribution without altering core code, and makes plugin initialization predictable and testable. Following it reduces bugs from mismatched expectations (missing fields, incorrect init semantics, hardcoded package names) and simplifies upgrading third-party libraries by keeping argument names and responsibilities explicit. --- ## Consistent module organization Keep code organized by responsibility and centralize reusable logic. Concretely: - Centralize helpers: move shared implementations (plugin loading, dataset parsing, prompt helpers, is_notebook, prompt wrappers, etc.) into a single utils or plugin package and import them from one place. Avoid copy-pasting variations of the same logic across files — this prevents drift, duplicate bugs, and inconsistent behavior (see plugin loaders and load_prompts). Example consolidation: replace duplicated _load_tagger_plugin/_load_scorer_plugin logic with a single load_plugin utility used by Evaluator. Example pattern: - utils.load_plugin(name: str, base_cls: type) -> type | instance - utils.load_prompts(spec: DatasetSpecification) -> list[str] - utils.prompt_select/text/password(...) that handle notebook vs terminal and are the single source of truth for user interaction - Enforce separation of concerns: keep UI and interaction code in the CLI layer (main.py); core classes (Model, Evaluator, Scorer) should expose well-typed methods and not prompt the user or perform I/O. If an operation needs user input, prompt in main then call a Model/Evaluator method with the chosen parameters (e.g., prompt in main, then call model.get_merged_model(strategy)). - Preserve strong typing and clear APIs when refactoring: keep explicit attributes and return types on public classes (avoid silently removing typed fields or returning ambiguous types). Use pydantic/BaseModel types for plugin settings and declare function return types so static checkers catch regressions. - Reduce duplication and improve resource handling: reuse existing computations (e.g., max_memory), consolidate is_notebook implementations, and avoid relying on del for cleanup — use context managers or explicit close/unlink behavior. - Small style rules that follow from organization: place imports at the top of modules, prefer named arguments (e.g., dim=...), remove unused imports, and use single authoritative helper functions rather than many inline special cases. How to apply: 1. Audit the codebase for duplicates of plugin loading, prompt handling, and dataset parsing; create single utilities and adjust callers to import them. 2. Move all prompt/text/password/select calls to a utils.prompt_* module and ensure main.py uses those helpers; domain objects must accept parameters rather than interact with users. 3. When extracting code, carry over type annotations and return types; add or preserve unit tests for behavior that was previously duplicated. 4. Replace flag-heavy control flow with clearer branching or loops and prefer context managers for resource lifecycle. Benefits: improved readability, fewer subtle behavioral regressions, simpler testing, and stronger static typing — all aligning with code style and maintainability goals. --- ## Config schema conventions Provide a clear, stable, and discoverable configuration schema. Apply the following rules to all TOML/environment configs: 1) Use self-documenting values - Avoid magic integers/booleans for multi-way choices. Prefer explicit enum/string values. Example: replace direction numeric codes with names: scorers = [ { plugin = "heretic.scorers.refusal_rate.RefusalRate", direction = "MINIMIZE", scale = 1.0 } ] - Use named methods for optional features (future-proofing): quantization_method = "bnb_4bit" # instead of load_in_4bit = true 2) Encode mutually exclusive or dependent options as a single enum - When multiple booleans imply combinations (e.g., compute_normalized & preserve_magnitudes), replace them with an enum so the intent is explicit and invalid combos are impossible: row_normalization = "none" | "row_normalize" | "row_normalize_and_restore_magnitudes" 3) Standardize plugin-scoped tables and plugin import paths - Use a documented convention for plugin configuration keys so settings are discoverable and validated. Example conventions: # For scorer-wide settings [scorer.RefusalRate] # For instance-specific settings (suffix with instance name) [scorer.RefusalRate_instanceA] - Plugin implementations should be specified as importable module paths (importlib-style). Example: tagger = "heretic.taggers.keyword.KeywordRefusalDetector" - If filesystem-path loading is required, document and implement it explicitly; otherwise require importable module paths and document how to extend PYTHONPATH. 4) Validate and warn on conflicts or removed/renamed keys - Emit a config validation step that: - Ensures file ordering/keys are present and documents preferred order (e.g., mirror config.py for readability). - Warns when plugin-scoped keys collide with instance-name conventions. - Flags removed or interdependent settings (e.g., deprecated kl_divergence_scale/kl_divergence_target) and provide migration guidance. 5) Maintain backward-compatibility with deprecation policy - When changing a config shape, provide a clear migration path and keep the old key working with warnings for at least one release, or provide a converter tool to update user configs. How to apply in practice - Implement a config schema validator that enforces enums, recognized plugin table names (scorer. and scorer._), and emits warnings for collisions and deprecated keys. - Document examples in config.default.toml and note the canonical order (e.g., follow config.py order) so users can scan settings easily. Example (combined TOML): # Top-level list of scorers with explicit directions scorers = [ { plugin = "heretic.scorers.refusal_rate.RefusalRate", direction = "MINIMIZE", scale = 1.0 } ] # Plugin path (importable module path) tagger = "heretic.taggers.keyword.KeywordRefusalDetector" # Plugin-specific settings [scorer.RefusalRate] good_evaluation_prompts = { dataset = "mlabonne/harmless_alpaca", split = "test[:100]", column = "text" } # Enum-valued options quantization_method = "bnb_4bit" row_normalization = "row_normalize_and_restore_magnitudes" References: discussions 0–7. --- ## Surface errors clearly Rule: Fail fast, validate assumptions, and distinguish user cancellation. Motivation - Hidden or silently handled errors lead to incorrect behavior, confusing UX, and hard-to-debug failures (e.g., silently ignoring invalid saved study settings, treating Ctrl+C as a legitimate choice, or swallowing invalid split specs). How to apply 1. Don’t swallow exceptions silently. If a library call or validation can fail, either let the exception propagate or catch it and re-raise with additional context. Only catch exceptions when you can meaningfully handle or recover; otherwise surface them to the caller/user. Example: remove broad try/except that hides JSON validation errors and instead let it fail with context. Bad: try: old_settings = Settings.model_validate_json(previous_settings) can_resume = True except ValidationError: can_resume = False Good: old_settings = Settings.model_validate_json(previous_settings) # raises on error — user sees the problem 2. Validate inputs and runtime assumptions before use. Check types, existence, and object state rather than assuming a shape or presence. If an assumption is violated, raise a clear error explaining the mismatch. - Verify fields are tensors/modules before using or indexing them. - When computing slices from user-provided split strings, validate and raise instead of silently using the whole dataset. Example (slice parsing): start, end = _get_split_slice(split_str, len(prompts), "_") # raise on invalid spec 3. Treat user cancellation distinctly. Do not conflate None/empty input with a legitimate selection. If a prompt returns None (e.g., Ctrl+C), cancel the current operation or surface that the user aborted instead of picking a default value or exiting the program unexpectedly. Example: merge_choice = prompt_select(...) if merge_choice is None: # user cancelled — abort or ask again, do not treat as "adapter" raise UserCancelledError("merge aborted by user") 4. Explicitly handle partial or incomplete state. Detect incomplete trials or partial writes using explicit state/flags (e.g., trial.state or a user_attr), and decide one clear behavior: ignore incomplete entries when computing results, extend target counts to account for incomplete trials, or remove incomplete records during resume — but do not silently miscount trials. - Use trial.state to check completeness before counting toward n_trials. 5. Provide clear, contextual error messages. When re-raising or failing, include what failed and why, and if appropriate, how to recover (e.g., suggest correcting a split spec or re-running with a different study checkpoint). Why this matters - Users need actionable errors (not silent defaults) to fix configuration or data issues. - Distinguishing cancellation prevents accidental destructive behavior and bad UX. - Validations prevent downstream crashes and nonsensical output. Follow-up checklist for code reviewers - Is there any broad try/except that hides failures? If yes, remove or narrow it and add context when re-raising. - Are user inputs validated or silently defaulted? If defaulting, is that explicit and documented? If not, raise an error. - Is Ctrl+C / prompt cancellation handled explicitly (None vs selection)? - Are runtime assumptions (types, states) checked before use? References: 1,2,3,4,5,6,7,8,9,10,11 --- ## Handle nullable values Treat None/absent values explicitly and guard attribute access. Motivation: user input, storage APIs, optional configuration, and runtime objects can all produce None or lack expected attributes. Implicitly assuming presence leads to data loss (e.g., deleting checkpoints on a cancelled prompt), brittle logic, and runtime errors. Rules and how to apply them: - Use Optional typing to model nullable semantics and document what None means. Prefer existing option types over ad-hoc enums/sentinels. Example: ObjectiveDirection: use optuna.StudyDirection | None where None = "do not optimize". - Always check return values that can be None before acting. For interactive prompts or library calls that may return None (e.g., user cancels), handle the None case explicitly instead of treating it as a valid choice. Example: choice = prompt_select("What do you want to do?", choices) if choice is None: print("Operation cancelled") return if choice == "continue": ... - When reading from storage/APIs, distinguish between None and empty collections and fail fast if invariants are violated. Prefer explicit checks over assumptions like "there is always one study". Example: try: study_id = storage.get_study_id_from_name("heretic") except KeyError: study_id = None if study_id is None: # no study — handle cleanly - Guard attribute access on heterogeneous runtime objects. Use hasattr/isinstance checks or explicit casting/typing before accessing .weight, .device, or plugin class attributes. Example: if hasattr(module, "weight"): v = layer_refusal_direction.to(module.weight.device) else: # handle tensor or non-weight module path - Rely on framework validation (e.g., pydantic.model_validate) for defaults, but still verify the validated object is present and of the expected type before use. Example: settings_obj = Settings.model_validate_json(maybe_previous_settings) if settings_obj is None: # handle missing or invalid settings - Fail fast and be explicit: if an assumption about presence/shape/type is critical and violated, raise a clear error instead of proceeding silently. Benefits: reduces accidental data loss, prevents unexpected None-driven behavior, makes control flow explicit, and improves safety when interacting with external APIs and heterogeneous objects. --- ## Optimization algorithm compatibility When implementing or changing optimization code (samplers, objectives, and result selection), ensure algorithmic correctness, preserve sampler assumptions, and prefer explicit post-processing over ad‑hoc objective hacks. Why: Incorrect assumptions about samplers, unclear trial counting, off-by-one indexing, or hidden objective tweaks can silently break search quality or produce confusing results. The rule reduces bugs and makes behavior auditable. Checklist (practical actions): - Validate sampler constraints before changing parameter conditioning - If using multivariate TPE, avoid introducing conditional/variable-range params that the sampler does not support, or adjust sampler options (e.g., grouping) deliberately and consistently. - Example: do not move from unconditional sampling to conditional sampling without ensuring the sampler remains valid. - Compute trial counts and statuses in one clear place - Count completed trials once and use that to adjust remaining trials rather than maintaining ad-hoc "extra" counters. - Example: completed_trials = [t for t in study.trials if t.state == TrialState.COMPLETE] remaining = max(0, desired_n_trials - len(completed_trials)) - Don't change the objective to fix selection/display issues; post-process instead - Keep the objective function simple and theoretically justified. If the Pareto/front presentation shows ties or ambiguity, resolve those when selecting best trials rather than altering the objective scoring. - Example post-processing (derive Pareto front from completed trials): sorted_trials = sorted( completed_trials, key=lambda t: (t.user_attrs['refusals'], t.user_attrs['kl_divergence']) ) best = [] min_div = float('inf') for t in sorted_trials: kld = t.user_attrs['kl_divergence'] if kld < min_div: min_div = kld best.append(t) - Be explicit about indexing and distances (avoid fenceposts) - When expressing distances or ranges over indices, document whether you mean count (n) or last index (n-1). Prefer using clear names (num_layers, last_layer_index) and compute derived values using the correct base. - Example: if n = number of layers, largest index distance = n - 1; use 0.6 * (n - 1) if you intend a fraction of the index span. - Prefer simple, well-justified changes over complex heuristics - If smoothing or interpolation is proposed to "improve" optimizer behavior, require theoretical justification or strong, reproducible experimental evidence; prefer linear/simple approaches and clearly note any new tuning parameters. When to apply: any change touching sampling logic, objective computation, trial bookkeeping, or final selection of best trials. Following this guidance improves correctness, reproducibility, and debuggability of optimization code. --- ## sanitize filesystem inputs When constructing filesystem paths or filenames from external input (model names, user-provided identifiers, etc.), treat those strings as untrusted. Whitelist allowed characters, disallow dots and path separators, and verify the final path stays inside the intended directory to prevent path traversal or accidental file access/deletion. Why: Allowing '.' or path separators can enable path traversal (e.g., "model/../../path") or surprising behavior later if code changes. This is a security vulnerability and should be mitigated by input validation and path containment checks. How to apply: - Prefer a strict whitelist of characters (e.g., letters, digits, underscore, dash). Do not allow '.' or os.path.sep characters. - After building a path, canonicalize it with os.path.normpath and verify it is a child of the intended directory. - Consider using a safe mapping (hash or UUID) instead of the raw name when appropriate. Example (based on the discussion): # safe sanitizer import os import re ALLOWED = re.compile(r"^[A-Za-z0-9_-]+$") # note: no dot def safe_name(name): if not ALLOWED.match(name): raise ValueError("invalid name") return name base_dir = settings.study_checkpoint_dir user_name = safe_name(model_name) filename = os.path.join(base_dir, user_name + ".json") # defense-in-depth: ensure containment norm_base = os.path.normpath(base_dir) norm_path = os.path.normpath(filename) if not norm_path.startswith(norm_base + os.path.sep) and norm_path != norm_base: raise ValueError("resulting path escapes base directory") References: discussion indices [0]. --- ## Determinism and compatibility When working on LLM inference/engines, ensure (1) determinism tests actually test the intended invariants, (2) optional GPU-accelerated kernels are only loaded when the hardware supports them (with a safe fallback), and (3) KV-cache shape assumptions are documented accurately. - Determinism tests: structure assertions so the generation invariants change *only* by the parameters you intend. - Example (temperature=0 should ignore randomness; outputs should match across different seeds for the same prompt): ```python prompt = [261, 72, 101, 108, 108, 111] engine = Engine(MockModel(), ByteTokenizer()) r1, _ = engine.generate_batch(prompt, temperature=0.0, max_tokens=5, seed=1) r2, _ = engine.generate_batch(prompt, temperature=0.0, max_tokens=5, seed=42) r3, _ = engine.generate_batch(prompt, temperature=0.0, max_tokens=5, seed=123) assert r1 == r2 == r3 ``` - Hardware compatibility: gate kernel loading by compute capability to avoid runtime “no kernel image” crashes; optionally fall back to a compatible import/wheel. - Example: ```python flash_attn = None if torch.cuda.is_available(): if torch.cuda.get_device_capability()[0] >= 9: flash_attn = get_kernel('varunneal/flash-attention-3').flash_attn_interface else: import flash_attn_interface as flash_attn # fallback ``` - KV-cache invariants: ensure assertions/comments match the real dimension constraints used by prefill/attention (e.g., remove incorrect dimension references and explicitly note fixed indices like the K/V pair dimension when applicable). --- ## consistent identifier naming Prefer clear, consistent, and semantic names for variables, classes, config keys, and section labels. Use these concrete rules when naming: - Use nouns for metrics/objects and verbs for actions. Prefer semantically meaningful units (e.g., use RefusalRate rather than CountRefusals) so scales are interpretable and independent of context: # bad scorers = [ ["heretic.scorers.count_refusals.CountRefusals", "minimize", 1.0] ] # good scorers = [ ["heretic.scorers.refusal_rate.RefusalRate", "minimize", 1.0] ] - Make units explicit in the name when scale matters (Rate, Count, Score, Probability). If a value depends on dataset size, prefer a rate or normalized form. - Namespace plugin/config sections by type to improve discoverability and avoid name collisions. Prefer hierarchical section names for plugin classes: e.g. use scorer.RefusalRate instead of a top-level [RefusalRate] when the setting belongs to scorers: # good [scorer.RefusalRate] threshold = 0.05 - Keep boolean/flag names concise and consistent in voice and plurality. Avoid long ad-hoc prefixes unless they add meaning; use a stable verb form (orthogonalize_*, preserve_*) and consistent plurality: # bad abliteration_orthogonal_project = false abliteration_preserve_magnitude = false # better orthogonalize_direction = false preserve_magnitudes = false - Balance namespacing with CLI ergonomics. If deep nesting would complicate common overrides, prefer a flat name that remains concise and consistent; otherwise prefer namespacing for clarity. Checklist to apply during review: - Is the identifier a noun (object/metric) or verb (action)? Does the form match its role? - Does the name include units/scale when needed (Rate/Count/etc.)? - Are section/table names grouped by category (scorer/, modifier/, etc.)? - Are boolean flags concise and consistent in verb/noun order and plurality? - Would namespacing harm common operations (CLI overrides)? If so, choose a shorter flat name following the same conventions. Following these rules reduces ambiguity, makes configuration values interpretable (especially scales), and keeps naming consistent across code and config. --- ## Capability-Guarded Configuration When code depends on environment/build features (SIMD/FP16 availability, OpenCV versioned APIs, packing layout support, OS/ABI-specific macros), you must (1) gate the code at compile time with the correct macros and (2) reflect the real capability in the backend’s `support_*` flags so the framework won’t select an unsupported execution path. Apply this as a standard checklist: - Optional dependencies: wrap includes/usages in the correct version guards (e.g., `CV_MAJOR_VERSION`/`CV_MINOR_VERSION`). - SIMD/FP16 paths: guard the *whole* implementation and call sites with the precise feature expression (e.g., NEON + the required FP mode), not only `__ARM_NEON`. - Backend packing/layout: if a packing layout or axis is not implemented, disable it in `create_pipeline()` (e.g., set `support_packing = false` or the equivalent packing flags), and then you can remove/avoid unused unpacking glue. - OS/arch macros: prefer correct architecture detection macros for each platform target (e.g., consider `_WIN32` when detecting x64). Example patterns: ```cpp // 1) Version-gated optional headers #if (CV_MAJOR_VERSION >= 3) #include #endif // 2) SIMD/FP16 gated implementation #if defined(__ARM_NEON) && (__ARM_FP & 2) static int lstm_fp16(...){ /* fp16 NEON path */ } #endif // 3) Capability flags match implementation int InnerProduct_arm::create_pipeline(const Option& opt) { if (axis == 1) support_packing = false; // packing/layout not implemented for this axis return 0; } // 4) If you disable packing support, don’t keep unpacking logic around if (!support_vulkan_packing && !support_vulkan_any_packing) { // avoid selecting unpack/convert glue; only accept supported layouts } ``` This prevents build-breaks on unsupported platforms, avoids dead/incorrect code paths, and ensures runtime execution matches what the backend actually supports. --- ## Justify dependency and build pins Any config change that affects build/runtime behavior (dependency version pins, feature flags, build backend settings, tool/target sources like GPU wheels) must include a concrete compatibility rationale and align with the build tooling or runtime environment. How to apply: - For **minimum versions**, state the exact capability that requires it (e.g., protocol support) and the cutover version. - For **feature flags** (e.g., maturin/pyo3), state *why* it’s required for your install mode and runtime (editable installs, Docker multi-stage, avoiding dynamic linkage to build-stage `libpython`). - For **version bumps**, explain the dependency constraint (e.g., must match maturin; an upstream library can’t support the newer version yet). - For **environment-specific sources/targets** (CUDA/ROCm), document the compatibility tradeoffs (device-specific wheels vs multi-device, whether ROCm is bundled, which versions to prefer). Example (`pyproject.toml`): ```toml [build-system] requires = ["maturin>=1.9.6,<2.0"] build-backend = "maturin" [tool.maturin] features = ["pyo3/extension-module"] # Needed so editable installs and Docker multi-stage builds don't depend on build-stage libpython. [project] dependencies = [ # datasets' hf:// downloader requires pyarrow >= 21.0.0 "pyarrow>=21.0.0", ] ``` Acceptance check: - Every version/feature/source addition has a short “why” comment tied to a specific compatibility requirement; otherwise revert or move the change behind an explicitly documented constraint. --- ## preserve dtype and shapes When writing PyTorch code, preserve tensor dtypes and devices and be explicit about vector/matrix shapes to avoid precision loss, incorrect broadcasting, and unnecessary CPU allocations. Why: mixed-precision and quantized weights are common in model deployment. Unnecessary up/downcasts, implicit device transfers, and incorrect assumptions about 1D tensor shapes (torch treats a 1D tensor as shape (d,) and matmul/outer have specific shape requirements) lead to subtle correctness and performance bugs. Rules (actionable): - Do not cast dtypes unless required. If a vector is already float32, avoid .to(torch.float32) again; prefer only changing device: v = v.to(module.weight.device) - When projecting against possibly low-precision weights, do projection math in a safe compute dtype, but avoid redundant round-trips (downcast then upcast). Example: if refusal_directions is float32 and W is bfloat16/4-bit, move the vector to W's device but keep its dtype: # good: preserve dtype, only change device v = layer_refusal_direction.to(matrix.device) r_transpose_W = torch.matmul(v, matrix) matrix.sub_(weight * torch.outer(v, r_transpose_W)) - Be explicit about shapes when using matmul vs outer: - Use torch.matmul for vector-matrix products where one operand is 1D (d,) and the other is (d, k). torch.matmul handles (d,) as (1, d) prepended internally. - Use torch.outer(a, b) when both a and b are 1D column vectors and you want the full outer product (d, k). Do not pass shaped tensors like (d,1) and (1,k) to torch.outer; prefer 1D tensors. - Avoid creating tensors on CPU unless necessary. Most torch operations preserve the source device; respect the device of source tensors to prevent implicit transfers and extra memory usage. - API/type clarity: annotate functions that return modules vs tensors correctly (e.g., dict[str, list[torch.nn.Module]]), and explicitly handle LoRA/quantization lifecycle (attach adapters without unnecessary weight changes; when merging on quantized models, reload base model on CPU and copy adapter weights). Example (combined pattern): # r is (d,) float32 already r_device = r.to(matrix.device) # r_device: (d,), matrix: (d, k) -> torch.matmul yields (k,) r_transpose_W = torch.matmul(r_device, matrix) # outer(r, r_transpose_W) -> (d, k) matrix.sub_(weight * torch.outer(r_device, r_transpose_W)) Apply these guidelines consistently to avoid unnecessary precision loss, incorrect broadcasting, and extraneous device transfers when working with models, LoRA adapters, and quantized weights. --- ## limit CI tokens {% raw %} Always prefer the built-in GITHUB_TOKEN, explicitly document why it’s needed, and grant it only the minimum permissions required. For third‑party actions that call the GitHub API, pin them and justify token usage in the workflow so reviewers can verify scope and intent. Why: automatic tokens are safer than adding shared secrets; minimizing permissions reduces blast radius if an action is compromised; pinning and documenting lets reviewers assess supply‑chain risk. How to apply: - Use GITHUB_TOKEN instead of custom secrets when possible. - Explicitly set repository permissions to the least privilege needed (example below sets read-only access to pull requests). - Pin actions to a specific version/release and include a short comment explaining why the token is required. - Prefer pull_request over pull_request_target unless you explicitly need base-repo context; if using pull_request_target, be extra cautious because it runs in the base repo context. Example (from discussion): name: Lint PR on: pull_request_target: types: [opened, reopened, edited] jobs: main: name: Validate PR title runs-on: ubuntu-latest permissions: pull-requests: read # minimal permission needed to read PR metadata steps: - uses: amannn/action-semantic-pull-request@v6 # pin action env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # builtin token; documented above Checklist for reviewers: - Is GITHUB_TOKEN required? Is the reason documented? - Are permissions scoped to the minimum (read vs write)? - Is the action pinned and from a trusted source? - Could pull_request be used instead of pull_request_target to reduce risk? References: [0] {% endraw %} --- ## Cache keys drive rebuilds When using uv to build Python extensions via PEP 517 (e.g., maturin), ensure cache invalidation is keyed to the actual build inputs. Configure `tool.uv.cache-keys` so builds rerun only when the underlying sources for the compiled artifact change—especially Rust sources and Cargo manifests—rather than rebuilding whatever project owns the root `pyproject.toml`. Apply this by: - Adding Rust build inputs to `tool.uv.cache-keys` (e.g., `src/**/*.rs`, `Cargo.toml`, `Cargo.lock`, or the whole crate dir like `rustbpe/**`). - Including the crate in the workspace so uv associates changes with the correct package (e.g., `rustbpe = { workspace = true }`). - Verifying `uv sync` / `uv run` actually rebuilds the intended artifact when Rust code changes. Example: ```toml [tool.uv] # Invalidate build cache when Rust crate inputs change cache-keys = [ { file = "pyproject.toml" }, { file = "rustbpe/**" }, # alternatively, more targeted keys like: # { file = "src/**/*.rs" }, # { file = "Cargo.toml" }, # { file = "Cargo.lock" } ] # Ensure the crate is part of the workspace so the right package rebuilds [rustbpe] # (or in the relevant uv sources section) # rustbpe = { workspace = true } ``` --- ## Spec-aligned Algorithm Correctness All algorithm implementations must be spec-aligned for the exact operator variant, tensor shapes/axes, and boundary conditions. Before merging, developers should explicitly verify that special cases and out-of-bound behavior follow the framework/ONNX semantics; avoid “one-size-fits-all” code paths that silently produce wrong results. Apply these checks: 1) Operator variant semantics must match the spec - If an operator has multiple semantics (e.g., hard vs soft shrink), implement them separately or with a correctness-preserving conditional. 2) Boundary/padding modes must apply to every sampled neighbor - For sampling/interpolation/grid ops, out-of-bound neighbor handling must respect padding_mode/align_corner. It’s not enough to “fix the coordinate”; the neighbor value lookup must also follow the same padding behavior. 3) Use integer-safe floor/ceil for index mapping - When converting continuous output coordinates to input indices, prefer integer arithmetic that matches floor/ceil definitions to avoid float rounding issues. Example pattern (floor/ceil div): ```cpp // floor div: ih0 = floor(h*i/out_h) int ih0 = (h * i) / out_h; // ceil div: ih1 = ceil(h*(i+1)/out_h) int ih1 = (h * (i + 1) + out_h - 1) / out_h; ``` 4) Shape/axis/loop structure must match the actual Mat layout - When axis-specific behavior exists (e.g., InnerProduct), ensure loops cover all required dimensions and writes target the correct logical indices (don’t assume a 2D layout when the tensor is 3D+). 5) Special cases must not be routed through general logic - If an input is a vector/1D tensor (or any other structural special case), ignore unrelated parameters (e.g., resize_type) and keep that logic in a dedicated branch. 6) Output type must match the source spec - If the spec defines an integer tensor output, don’t return float to “approximate”; confirm downstream layers won’t break on precision or type assumptions. 7) Add minimal correctness tests - For each algorithmic change, include at least one test case per (a) variant (hard/soft, avg/max), (b) padding_mode/boundary scenario, and (c) axis/shape configuration, plus a “large value” case for integer-typed specs. --- ## Graceful Error Propagation When writing library code, never hard-terminate or silently ignore failures. Always (1) validate inputs/shape compatibility correctly (including pack/elempack and dynamic dims), (2) signal errors with consistent return codes, and (3) propagate error statuses from lower-level operations to the caller. Apply these rules: - Propagate return values: if a lower-level API returns an error/status, return it (or convert it to a documented error code) instead of discarding it. - Avoid assert/exit in library code: replace `assert(0)`/process termination with a returned error code so the caller can decide how to recover. - Use consistent error codes: pick and follow conventions (e.g., `-1` for invalid parameter, existing `-100` for allocation failure, etc.). - Validate shapes with packing and dynamic dims: reject only when the producer/consumer shapes are known-static and truly incompatible; handle dynamic dims (non-positive) and elempack scaling. Example: propagate and handle submit errors ```cpp // Bad: ignoring status cmd.submit_and_wait(); return 0; // Good: propagate to caller return cmd.submit_and_wait(); ``` Example: avoid assert(0) in library code ```cpp switch (impl_type) { case 1: /* ... */ break; case 2: /* ... */ break; // ... default: return -1; // invalid impl_type } ``` --- ## Consistent Semantic Identifiers When adding/changing code, use names that (1) match existing project conventions, (2) clearly express intent, and (3) avoid reserved/problematic identifier patterns. Rules: - Avoid reserved naming: do not use local variable names starting with `_` (e.g., prefer `top`, `front`, `behind` over `_top`, `_front`). - Use semantic, intent-revealing names: avoid vague placeholders like `size_threshold`; prefer names that encode behavior/meaning (e.g., `budget_count_threshold` / `budget_drop_threshold`). - Follow established naming patterns: use the project’s width/height/etc. suffix conventions consistently (e.g., `kernel_w`, `stride_w`, and similarly `out_w`, `out_h`). - Align dimension/axis naming to ncnn semantics: use the same axis ordering and naming expected by the codebase (commonly `z y x` meaning dep/row/col), and ensure axis transforms follow ncnn conventions. - Keep platform and parameter identifiers correct: use the correct architecture macro names and ensure variable/index names correspond to the documented parameter meaning/order. Example (naming fixes): ```cpp // Bad: reserved leading underscore + vague intent int _top; size_t size_threshold = 10; // Good: non-reserved + semantic intent int top; size_t budget_drop_threshold = 10; // Good: follow *_w / *_h conventions int out_w = pd.get(18, out_h); ``` --- ## Backwards-Compatible API Evolution When evolving or integrating client-facing interfaces (CLI/API) and platform-dependent APIs, preserve compatibility across existing clients and across SDK/platform versions. Apply these rules: 1) Backward-compatible interface changes - If you add an optional parameter, place it at the end so existing positional arguments keep working. Example (CLI): ```cpp // Old: prog caffeproto caffemodel ncnnproto ncnnbin quantizelevel int8scaletable // New: prog ocr|noocr caffeproto caffemodel ncnnproto ncnnbin quantizelevel int8scaletable // Implementation rule: keep the new optional argument(s) after existing ones, and // only extend argv parsing in a way that preserves old argc patterns. ``` 2) Guard optional platform/API features - Never assume a flag/enum/symbol exists on every build environment. - Use feature checks and conditional compilation before setting flags. Example (Vulkan-like pattern): ```cpp VkInstanceCreateInfo instanceCreateInfo{}; instanceCreateInfo.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO; // Prefer feature/support-based gating over hard-coding. if (support_portability_enumeration) { instanceCreateInfo.flags |= VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR; } ``` 3) Use compatibility shims for missing SDK symbols - If an enum/definition is missing in older headers, add a controlled header shim (e.g., `vulkan_header_fix.h`) rather than sprinkling ad-hoc defines throughout code. 4) Don’t leak platform/ISA-specific details into stable interfaces - Keep ISA/rvv-specific parameters (e.g., vector length) resolved inside the implementation instead of being part of the function signature. Together, these practices keep client interfaces stable for existing users while still allowing safe use of newer platform capabilities. --- ## Test independence design Tests should be designed to be independent and avoid coupling to implementation details. Use public interfaces rather than accessing internal state, prefer mocked or fake data over external dependencies, and keep tests general rather than tightly coupled to specific implementations. Key principles: - Avoid accessing internal state like `raw_points` in test cases - use proper public interfaces like `handle_log` instead - Use made-up or mocked data rather than requiring external handlers when the test doesn't specifically need to test that integration - Design tests to know as little as possible about specific implementations (e.g., car brands) to keep them general and maintainable Example of good practice: ```python # Instead of accessing internal state: est.raw_points["lat_active"].append(True) # Use the public interface: est.handle_log(log_message) ``` This approach makes tests more maintainable, less brittle to refactoring, and easier to understand by focusing on the component's public contract rather than its internal implementation. --- ## Unrolled SIMD Locality When optimizing hot kernels (SIMD/vectorized paths), remove avoidable overhead and improve locality: 1) Unroll small fixed-size tails (e.g., remainder=4) - Replace remainder loops with straight-line stores/loads to eliminate loop counters and per-iteration branches. - Example (tail of 4 elements with alternating sources): ```cpp // Instead of: for (int i=0;i<4;i++){ if(i%2)... } // Do a straight-line unroll: { outptr[0] = ptr0[0]; outptr[1] = ptr1[0]; outptr[2] = ptr0[1]; outptr[3] = ptr1[1]; ptr0 += 2; ptr1 += 2; outptr += 4; } ``` 2) Use packed/contiguous intermediate buffers in vector code - Prefer layouts that store multiple small fields (e.g., 4 lanes of coeffs/offsets) contiguously to reduce pointer chasing, TLB misses, and cache fragmentation. - Example style: ```cpp // Instead of separate small-dim Mats that increase pointer indirections, // create a single contiguous layout: offset_blob.create(outw, outh, elemsize * 4, 4, opt.workspace_allocator); value_blob.create(outw, outh, elemsize * 2, 2, opt.workspace_allocator); // (Or merge offset+value into one buffer when feasible.) ``` 3) Keep ISA guards and branching structure “compiler-friendly” - Use correct feature checks (don’t assume `__AVX2__` implies `__AVX__`): `#if defined(__AVX__) && defined(__AVX2__)`. - Avoid placing `elempack==1` scalar handling inside SIMD-only macros in a way that blocks optimization; keep `elempack` branching clear at the appropriate scope. 4) For reductions, avoid inefficient reduction patterns - Don’t perform costly “reduce” operations inside tight loops; restructure so reduction is done efficiently (e.g., accumulate vectors, then reduce once). These rules target the same bottlenecks discussed: loop/branch overhead on tiny remainders, poor memory locality for intermediates, and avoidable SIMD/ISA/reduction inefficiencies. --- ## use context managers concurrency When working with concurrent operations involving shared resources or processes, use context managers and explicit synchronization to ensure proper cleanup and thread safety. This prevents resource leaks, race conditions, and ensures graceful shutdown even when operations are interrupted. For process management, wrap subprocess operations in context managers instead of relying on atexit handlers: ```python # Instead of atexit.register() with ProcessManager() as pm: xvfb_proc = pm.start_process(xvfb_cmd, env) ui_proc = pm.start_process(ui_cmd, env) # processes automatically cleaned up on exit ``` For shared resources accessed by multiple threads, use explicit locking: ```python class AudioProcessor: def __init__(self): self.lock = threading.Lock() # Add a lock for thread safety self.sound_data = [] def process_audio(self, data): with self.lock: self.sound_data.append(data) ``` When adding concurrency to existing APIs, maintain backward compatibility by encapsulating threading details within the implementation rather than exposing them to consumers. This allows you to improve responsiveness (like preventing UI freezing) without breaking existing code that depends on the original synchronous interface. --- ## Configuration defaults consistency Ensure configuration parameters have appropriate default values, consistent naming conventions, and centralized default management. When adding new configuration keys, consider security implications for defaults (e.g., audio recording should default to off), maintain consistent naming patterns with existing keys, and centralize default values in the configuration structure rather than scattered throughout the codebase. Example of good practice: ```cpp inline static std::unordered_map keys = { {"AdbEnabled", {PERSISTENT}}, // Consistent with SshEnabled naming {"RecordAudioFeedback", {PERSISTENT, BOOL, "0"}}, // Default off for privacy // Centralized defaults as third parameter }; ``` This approach improves maintainability, reduces configuration errors, and ensures security-conscious defaults for sensitive features. --- ## Centralize error handling utilities Create reusable error handling functions that accept custom error callbacks instead of duplicating error handling logic across multiple files. This approach provides flexibility in error response while maintaining consistent error handling patterns throughout the codebase. When implementing system calls or operations that can fail, use a centralized utility function that accepts an error message and a callback for custom error handling. This eliminates code duplication and allows each call site to define appropriate failure responses. Example implementation: ```cpp template int safe_ioctl(int fd, unsigned long request, void *argp, const char* error_msg, ErrorCallback error_callback) { int ret; do { ret = ioctl(fd, request, argp); } while ((ret == -1) && (errno == EINTR)); if (ret == -1 && error_msg) { LOGE("ioctl failed: %s", error_msg); error_callback(); } return ret; } // Usage with custom error handling auto fail = [this, serial] { cleanup(); throw std::runtime_error("Error connecting to panda " + serial); }; safe_ioctl(spi_fd, SPI_IOC_WR_MODE, &spi_mode, "failed setting SPI mode", fail); ``` This pattern allows for consistent error logging while enabling call sites to implement appropriate cleanup, exception throwing, or recovery strategies based on their specific context. --- ## optimize mathematical mappings Use consistent units and data representations throughout mathematical calculations to avoid unnecessary computational overhead. When working with value ranges, prefer direct mathematical mappings over multiple conversions, and leverage utility functions for range transformations. For example, instead of converting between different units multiple times: ```cpp // Avoid multiple conversions int ir_percent = util::map_val(static_cast(ir_pwr), 0, static_cast(100*MAX_IR_POWER), 0, 100); // Better: work in consistent units, then map once int value = util::map_val(std::clamp(percent, 0, 100), 0, 100, 0, 255); ``` This approach reduces computational complexity, minimizes floating-point precision errors, and makes the code more maintainable by establishing clear data flow patterns. Choose the most natural unit for your domain and stick with it throughout the calculation pipeline. --- ## API backward compatibility Ensure API changes maintain backward compatibility to avoid breaking existing clients and workflows. When adding new functionality, use optional parameters with sensible defaults rather than required parameters. When versioning APIs, follow the `/api/v2/resource` pattern and maintain deprecated endpoints during transition periods to allow clients time to migrate. Key practices: - Add new parameters under "optional" sections with default values to prevent breaking saved workflows - Maintain existing API endpoints when introducing new versions until clients can migrate - Use proper versioning patterns like `/api/v2/userdata` rather than `/userdata-v2` - Plan migration strategies that allow both old and new APIs to coexist temporarily Example of backward-compatible parameter addition: ```python def INPUT_TYPES(s): return { "required": { "images": ("IMAGE", ), "filename_prefix": ("STRING", {"default": "ComfyUI"}) }, "optional": { "disable_metadata": ("BOOLEAN", {"default": False}) # New parameter as optional } } ``` This approach prevents breaking existing API workflows while enabling new functionality for clients that choose to adopt it. --- ## Explicit value specifications Always use explicit value specifications and type-safe handling to prevent undefined behavior and ensure predictable code execution. This includes specifying appropriate default values for configuration parameters and using platform-independent format specifiers for data types. For configuration defaults, be explicit about expected values even when they seem obvious: ```cpp // Good: Explicit defaults prevent undefined states {"UptimeOffroad", {PERSISTENT, FLOAT, "0.0"}}, {"UptimeOnroad", {PERSISTENT, FLOAT, "0.0"}}, ``` For type formatting, use portable macros to ensure correct behavior across platforms: ```cpp // Good: Type-safe formatting prevents undefined behavior LOGE("SV_ID != SLOT_NUMBER: %d %" PRIu64, msg->sv_id(), data->n()); // Alternative: Explicit casting for clarity LOGE("SV_ID != SLOT_NUMBER: %d %llu", msg->sv_id(), (unsigned long long)data->n()); ``` This approach prevents subtle bugs from implicit assumptions about default values or platform-specific type representations, ensuring consistent behavior across different environments and reducing the risk of undefined states. --- ## Design convenient APIs APIs should provide convenient methods that handle common operations directly, rather than requiring users to write helper functions or use verbose patterns. This improves developer experience and reduces boilerplate code. Key principles: - Build common functionality like type conversion into API methods themselves - Provide simple, direct constructor patterns for object creation - Avoid forcing users to chain multiple method calls for basic operations Example of good API design: ```python # Good: Simple constructor with direct parameter passing CC = car.CarControl(cruiseControl={'cancel': True}) # Avoid: Verbose chaining that could be simplified CC = car.CarControl.new_message(cruiseControl={'cancel': True}) test_car_controller(CC.as_reader()) ``` When designing APIs, consider what the most common use cases will be and optimize the interface for those scenarios. If you find yourself writing helper functions or seeing users write repetitive boilerplate, that's a signal the API could be more convenient. --- ## avoid expensive operations Identify and eliminate unnecessary expensive operations that can significantly impact performance. Common patterns to watch for include: 1. **Unnecessary deep copying**: Instead of using `deepcopy()` on large objects, build new dictionaries with only the required values. For example, rather than `copy.deepcopy(self.history[key])` and then removing unwanted fields, construct a new dictionary with only the needed data. 2. **Loop-invariant computations**: Move calculations that don't change between iterations outside of loops. For instance, if `interpolator(x)` produces the same result in every loop iteration, compute it once before the loop and store in a variable like `computed_spacing`. 3. **Missing caching for expensive operations**: Implement caching for frequently accessed heavy resources like models, file system operations, or computed values. Use model caches to "directly copy from cpu memory" rather than reloading from disk repeatedly. 4. **Redundant processing**: Avoid performing expensive operations on every function call when they could be done once or only when necessary. Check if computations can be moved to initialization or triggered only when input conditions change. Before implementing expensive operations, consider: Is this computation necessary every time? Can the result be cached? Can the operation be moved outside a loop or conditional block? These optimizations often provide significant performance improvements with minimal code changes. --- ## prefer dynamic configuration sources Use runtime-determined configuration sources instead of hardcoded values or static file parsing when more reliable alternatives are available. This improves robustness, cross-platform compatibility, and deployment flexibility. **Examples of preferred approaches:** - Use `importlib.metadata.version("package-name")` instead of parsing requirements.txt files for version information - Use `win32api.GetSystemDirectory()` instead of hardcoded paths like `"C:\Windows\System32"` - Read from runtime environment (like installed packages) rather than static configuration files when both options exist - Construct paths dynamically using `os.path.join()` instead of hardcoded absolute paths **Why this matters:** - Static files can become outdated or contain invalid data (like "max" instead of numbers in cgroup files) - Hardcoded paths break in different deployment environments or operating systems - Runtime sources reflect the actual current state rather than potentially stale configuration files - Dynamic configuration reduces maintenance burden and improves reliability across different environments **Implementation:** ```python # Instead of hardcoded paths: ICACLS_PATH = r"C:\Windows\System32\icacls.exe" # Use dynamic system paths: ICACLS_PATH = os.path.join(win32api.GetSystemDirectory(), "icacls.exe") # Instead of parsing static files: with open("requirements.txt", "r") as f: version = f.readline().split("=")[-1].strip() # Use runtime package information: from importlib.metadata import version frontend_version = version("comfyui-frontend-package") ``` --- ## Extract repeated logic When you notice code patterns being repeated across functions or methods, extract the common logic into separate, reusable functions. This improves maintainability, reduces bugs, and follows the DRY (Don't Repeat Yourself) principle. Look for opportunities to: - Extract repeated code blocks into helper functions - Split complex functions that handle multiple responsibilities - Create utility functions for common operations - Refactor similar conditional logic into shared functions Example of refactoring repeated logic: ```python # Before: Repeated logic in multiple places def get_free_memory(dev=None, torch_free_too=False): if os.path.isfile('/sys/fs/cgroup/memory/memory.limit_in_bytes'): with open('/sys/fs/cgroup/memory/memory.limit_in_bytes', 'r') as f: mem_used_total = psutil.virtual_memory().used mem_total = int(f.read()) # ... more logic def get_total_memory(dev=None): if os.path.isfile('/sys/fs/cgroup/memory/memory.limit_in_bytes'): with open('/sys/fs/cgroup/memory/memory.limit_in_bytes', 'r') as f: mem_used_total = psutil.virtual_memory().used mem_total = int(f.read()) # ... more logic # After: Extracted common logic def get_containerd_memory_limit(): if os.path.isfile('/sys/fs/cgroup/memory/memory.limit_in_bytes'): with open('/sys/fs/cgroup/memory/memory.limit_in_bytes', 'r') as f: mem_used_total = psutil.virtual_memory().used mem_total = int(f.read()) return mem_used_total, mem_total return None, None def get_free_memory(dev=None, torch_free_too=False): mem_used, mem_total = get_containerd_memory_limit() if mem_used is not None: # ... use extracted values ``` This approach makes code more maintainable, testable, and reduces the likelihood of introducing bugs when making changes. --- ## Platform-Targeted Flags When enabling/disabling CPU features or platform-specific APIs, derive decisions from the *configured target/platform* (toolchain/CMake target selection) and apply consistent compile-time guards across code and tests. Do not rely on compiler-defined feature macros that may differ between build/test environments. Apply it like this: - In CMake/toolchains: explicitly set feature flags for the target (and force them in the toolchain when the target requires it). ```cmake # Toolchain for an older/limited target set(NCNN_AVX OFF CACHE BOOL "Disable AVX" FORCE) set(NCNN_AVX2 OFF CACHE BOOL "Disable AVX2" FORCE) set(NCNN_SSE2 ON CACHE BOOL "Enable SSE2" FORCE) set(CMAKE_SYSTEM_VERSION 5.1) set(CMAKE_GENERATOR_PLATFORM "Win32") ``` - In headers/source: guard platform APIs/intrinsics with the correct target macros (prefer `_WIN32 && !(__MINGW32__)` over ad-hoc flags; keep intrinsics loads inside the matching arch block). ```c #if (defined _WIN32 && !(defined __MINGW32__)) #define WIN32_LEAN_AND_MEAN #include #include #endif #if __ARM_NEON float32x4_t _k0123 = vld1q_f32(kernel0); #else const float* k0 = kernel0; #endif ``` - In tests: determine capability based on the *target being executed* (x86/arm/Win32 target), not compiler macros like `__AVX__`. This prevents “works in net.cpp, fails in ctest” and “breaks armv7 without NEON” class regressions, and keeps feature gating consistent across the build and runtime/test environments. --- ## Conditional CMake Configuration When changing build configuration (compiler definitions, link libraries, compile/link flags), ensure it is applied only when the correct *feature option* is enabled and the *selected target/toolchain* actually requires it. Avoid unconditional/global flags that can break other platforms or remove the ability to disable features. Practical rules: - Gate configuration with the project’s option (e.g., NCNN_OPENMP) and/or a precise target/toolchain condition (e.g., ANDROID_NDK vs just ANDROID). - Prefer target-scoped, modern CMake integration (e.g., target_link_libraries with imported targets) over mutating global variables like CMAKE_CXX_FLAGS. - Only add compile/link flags that make sense for the produced artifact type (e.g., OpenMP linking is relevant for executables/shared/module builds, not for a static library target in isolation). Example pattern (OpenMP): ```cmake option(NCNN_OPENMP "build with OpenMP" ON) if(NCNN_OPENMP) find_package(OpenMP) if(OpenMP_CXX_FOUND) # Apply to the actual consuming target(s) target_link_libraries(my_executable PRIVATE OpenMP::OpenMP_CXX) endif() endif() ``` Example pattern (target/toolchain gating): ```cmake # Don’t treat any ANDROID-defined toolchain as an Android NDK build. if(ANDROID AND ANDROID_NDK) # android-specific flags/libs endif() # Don’t force XP-only definitions for every WIN32 build. if(WIN32 AND NCNN_TARGET_XP) target_compile_definitions(ncnn PUBLIC _WIN32_WINNT=0x0501 WINVER=0x0501) endif() ``` --- ## Avoid Performance Pessimization When optimizing for CPU/GPU speed, don’t accidentally remove fast paths via build/toolchain settings, and don’t add expensive memory-access patterns in the hottest kernels. Apply this standard: 1) Don’t globally disable ISA features or runtime CPU dispatch from generic toolchain files - Only apply ISA restrictions for the specific target (e.g., legacy OS/CPU) and keep that list explicitly documented. - Don’t redundantly set every descendant ISA knob when disabling a parent already covers it. - Be aware that disabling runtime CPU dispatch can eliminate optimized code paths (e.g., xop) even when the target CPU supports them. 2) In SIMD kernels, avoid unnecessary gather/indirection for contiguous data - If the source elements are contiguous, use normal vector loads (e.g., loadu/storeu) rather than gather instructions. - Gather is for irregular/index-driven access; using it “just to mask” typically wastes bandwidth/latency. 3) Keep SIMD tail handling simple and width-driven - Prefer clear “main loop + remainder” loops by SIMD width over complex `nn`/offset-tail bookkeeping. 4) Don’t assume `#pragma omp simd` will outperform hand-written intrinsics in hot paths - For critical x86 kernels that already use explicit intrinsics, extra pragmas usually add complexity with minimal speedup. Example (contiguous access vs gather): ```cpp // Bad: gather when srcptr is contiguous and offsets are sequential // __m256 v00_val = mask_gather_ps256(srcptr, v00_offset, mask); // Good: use vector load directly when indices are contiguous // (illustrative; exact mask logic depends on bounds) __m256 v00_val = _mm256_loadu_ps(srcptr + base_index); // apply mask/lerp/fma as needed ``` Example (width-driven tail loop instead of nn bookkeeping): ```cpp int x = 0; #if __SSE2__ #if __AVX__ for (; x + 7 < grid_size; x += 8) { // AVX body } #endif for (; x + 3 < grid_size; x += 4) { // SSE body } #endif for (; x < grid_size; x++) { // scalar remainder } ``` Net effect: you preserve the compiler/runtime ability to select the fastest supported implementation, and you prevent common “hidden” slowdowns from gather/indirection and overly complex SIMD tails. --- ## Platform-correct CI Pipelines Ensure CI/CD workflows build, test, and package artifacts in a way that is correct for each target platform/architecture—without running irrelevant jobs. Apply these rules: 1) Prefer dedicated toolchains; avoid hardcoded compiler/arch knobs unless the workflow explicitly documents and matches the toolchain. 2) Scope CI triggers and steps by actual feature/platform support. - If a feature is disabled or unsupported on a platform (e.g., Vulkan on esp32), do not trigger or build Vulkan-related paths. 3) Make dependencies explicit per arch and verify artifact completeness. - When packaging shared libraries (e.g., Vulkan/MoltenVK on macOS), wire the correct include/library paths for each arch and confirm the library is present during “repair/copy” steps. 4) Handle known toolchain/CI issues by gating, detecting, or temporarily disabling the failing job (and document why) so merges aren’t blocked by unrelated problems. Concrete example (macOS per-arch Vulkan wiring): ```yaml # x86_64 CIBW_ENVIRONMENT: | NCNN_VULKAN=ON Vulkan_INCLUDE_DIR=$GITHUB_WORKSPACE/vulkansdk-macos-1.3.236.0/MoltenVK/include Vulkan_LIBRARY=$GITHUB_WORKSPACE/vulkansdk-macos-1.3.236.0/MoltenVK/dylib/macOS/libMoltenVK.dylib ``` Concrete example (path-scoped CI triggering): ```yaml # Only run when relevant; don’t trigger for Vulkan-only subtree changes if Vulkan is off on: pull_request: paths: - '.github/workflows/windows-xp-clang.yml' - 'CMakeLists.txt' - 'src/*' # Omit 'src/layer/vulkan/**' if Vulkan support is disabled ``` Quick validation checklist for each platform/arch: - Does the workflow use the intended toolchain settings for that target? - Are only supported features being built/tested? - Are all required external runtime libs correctly pointed to and included in the final artifact? - If a toolchain job is known to fail in the CI environment, is it gated/disabled with a documented reason? --- ## Eliminate Shared Mutable State Ensure concurrent execution is race-free by (a) not storing per-inference mutable state in shared layer objects, (b) keeping OpenMP loop temporaries thread-local, and (c) using the correct synchronization primitive for the target platform. Apply these rules: 1) State must be owned by the running instance, not by the shared model/layer. - Avoid patterns like `mutable` members updated in `forward()`. - If an operator needs recurrent state (e.g., LSTM hidden/cell), pass it in via inputs and return updated state via outputs (so separate Extractors don’t race on the same layer object). Example pattern: ```cpp // Instead of: mutable Mat hidden, cell; hidden=...; cell=...; in forward() // Do: int forward(const std::vector& bottom_blobs, std::vector& top_blobs) { const Mat& hidden_in = bottom_blobs[HIDDEN_BLOB_INDEX]->data; const Mat& cell_in = bottom_blobs[CELL_BLOB_INDEX]->data; Mat hidden_out, cell_out; // compute hidden_out/cell_out... top_blobs[HIDDEN_OUT]->data = hidden_out; top_blobs[CELL_OUT]->data = cell_out; return 0; } ``` 2) In parallel loops, never let per-iteration data become shared state. - In `#pragma omp parallel for`, any pointer/variable that changes per iteration (e.g., `pc`, `pa`, `scales`, `bias`) must be thread-local or loop-local (declared inside the loop or as private variables), not shared across iterations. 3) Locking primitives must match platform semantics. - If a mutex/condition-variable implementation differs by OS/toolchain support, use macro guards so the concurrency contract holds on all targets (e.g., XP-compatible `CRITICAL_SECTION` vs newer primitives). --- ## Optional Null Safety Checks When code depends on possibly-missing inputs/outputs or optional attributes, do not index or read them unconditionally. Add explicit guards for presence and fall back to a safe default/overload. Apply this pattern: - For vector-based tensors: verify `bottom_blobs.size()` / `top_blobs.size()` before using fixed indices (e.g., hidden/cell), and if hidden/cell aren’t provided, delegate to the simpler overload. - For operator attributes: verify the attribute exists before reading it (e.g., `n.has_attr("eps")`); only then use the value, otherwise use the intended default. Example (vector forward fallback): ```cpp int forward(const std::vector& bottom_blobs, std::vector& top_blobs, const Option& opt) const { if (bottom_blobs.size() < 1 || top_blobs.size() < 1) return -100; // hidden/cell optional: only use them when present if (top_blobs.size() >= 3) { // access indices safely Mat& hidden_state = top_blobs[1]; Mat& cell_state = top_blobs[2]; return forward(bottom_blobs[0], top_blobs[0], hidden_state, cell_state, opt); } // safe fallback Mat& top_blob = top_blobs[0]; return forward(bottom_blobs[0], top_blob, opt); } ``` Example (attribute existence guard): ```cpp float eps = 1e-3f; // intended default if (n.has_attr("eps")) eps = n.attr("eps"); ``` Rule of thumb: if the code would otherwise dereference an index or consume an attribute that may not be present, you must add a guard and a fallback path before the dereference. --- ## Consistent terminology choices When introducing new terminology or naming conventions, ensure consistency with existing patterns in the codebase while prioritizing clarity and universal understanding. Before adding new names, identifiers, or terminology, review existing usage patterns and adopt the established conventions. When multiple options exist, choose the most widely understood and universally applicable terms. For example, when adding translations or interface text, check existing instances: "I saw that 'Associer' is the verb used in all other instances" and maintain that consistency. Similarly, when choosing between terminology options, select the "most universal way" that will be clear to the broadest audience. This applies to variable names, method names, UI text, comments, and any other identifiers where consistency and clarity are important for maintainability and user understanding. --- ## explicit null handling strategies Functions and APIs should employ explicit strategies for handling null/None values rather than leaving null handling ambiguous. Choose one of two approaches: 1. **Design out nulls**: Use sentinel values, default objects, or consistent data structures to eliminate the need for null checks 2. **Explicit null contracts**: If a function can return None, either document that all callers must handle None, or raise an exception instead **Avoid**: Returning None from functions without clear handling expectations, or requiring frequent isinstance/null checks due to inconsistent data formats. **Example of good null handling:** ```python # Option 1: Design out nulls with defaults def get_config(key: str) -> Config: return config_dict.get(key, DEFAULT_CONFIG) # Never returns None # Option 2: Explicit null contract def get_node(node_id: str) -> Node: node = self._find_node(node_id) if node is None: raise NodeNotFoundError(f"Node {node_id} not found") return node ``` **Example of problematic null handling:** ```python # Ambiguous - callers don't know if they need to handle None def get_node(node_id: str) -> Node | None: # Returns None sometimes, unclear when return self.nodes.get(node_id) ``` This approach prevents attribute errors, reduces defensive programming overhead, and makes null-handling expectations explicit in the codebase. --- ## optimize computational efficiency Implement memoization and guard clauses to eliminate redundant computations and improve algorithmic performance. Many algorithms can be significantly optimized by caching intermediate results and avoiding unnecessary work. Key optimization strategies: 1. **Use memoization for recursive functions** - Cache results of expensive recursive calls to avoid recalculating the same values multiple times 2. **Add guard clauses for conditional processing** - Check if work is needed before performing expensive operations 3. **Choose efficient iteration patterns** - Use lazy evaluation techniques like `islice` instead of creating full intermediate collections 4. **Ensure proper memoization scope** - Create memo objects at the appropriate scope to maximize reuse Example of proper memoization implementation: ```python # Before: Redundant recursive calculations def recursive_will_execute(prompt, outputs, node_id): # Expensive recursive computation repeated many times return calculate_dependencies(prompt, outputs, node_id) # After: Memoized version with proper scope memo = {} # Create memo outside the sorting algorithm output_node_id = min(to_execute, key=lambda a: len(recursive_will_execute(prompt, outputs, a, memo))) ``` Example of guard clause optimization: ```python # Before: Always processes string replacements def compute_vars(input, image_width, image_height): input = input.replace("%width%", str(image_width)) input = input.replace("%height%", str(image_height)) return input # After: Skip processing if no variables present def compute_vars(input, image_width, image_height): if '%' not in input: return input # Guard clause avoids unnecessary work input = input.replace("%width%", str(image_width)) input = input.replace("%height%", str(image_height)) return input ``` These optimizations can dramatically improve performance, especially in algorithms that process large datasets or perform repeated calculations. --- ## Optimize numerical precision When implementing AI operations that involve matrix multiplication or neural network components, explicitly support modern numerical precision formats (TF32, BFloat16, Float8) across different hardware backends. These precision formats significantly accelerate AI training and inference while maintaining acceptable numerical accuracy. For maximum performance: 1. Ensure consistent precision format support across hardware accelerators (CUDA, XPU, MKL-DNN) 2. Handle different accelerator types with appropriate conditionals: ```cpp if ((input_.is_cuda() || input_.is_xpu()) && input_.scalar_type() == ScalarType::Half) { // Use accelerator-specific optimizations } ``` 3. Implement specialized code paths for each precision format (ieee, tf32, bf16) based on the operation requirements 4. Add unit tests to verify numerical correctness when using reduced-precision formats These optimizations can lead to significant speedups in large model training and inference without requiring algorithm changes. --- ## Handle errors specifically Always be explicit and specific when handling errors rather than using catch-all approaches or implicit conventions. This improves code robustness, debuggability, and maintainability. When catching exceptions: 1. Catch specific exception types instead of using broad exception handlers 2. Only catch exceptions you can meaningfully handle 3. Consider returning None for recoverable failures instead of catching arbitrary exceptions ```python # Don't do this - catching all exceptions masks problems try: result = complex_operation() except Exception as exc: result = default_value # Which errors should actually be handled this way? # Do this - be specific about what you're catching try: result = complex_operation() except MemoryError: # Handle specific memory issues raise RuntimeError("Insufficient memory for operation") from exc except KeyError as e: # Handle missing keys appropriately return None # Indicate failure with explicit return ``` When raising or signaling errors: 1. Raise specific exceptions with clear messages rather than returning special values 2. Use enums or dedicated types for error conditions instead of magic numbers 3. Place validation before state mutation to keep system consistent during exceptions ```python # Don't do this - using special return values is error-prone def check_if_supported(): if not meets_requirements(): return False # Caller might miss this! # ... # Do this - be explicit about errors def check_if_supported(): if not meets_requirements(): raise RuntimeError("Requirements not met: missing XYZ") # ... # Order operations to maintain system integrity def perform_mutation(self, key): # First validate - may raise exceptions if key not in self.valid_keys: raise_args_mismatch() # Only mutate state after validation passes self.should_reconstruct = True self.output.side_effects.mutation(self) ``` By being specific about errors, you make code easier to debug and maintain while preventing your system from entering invalid states. --- ## Prevent null pollution Design your code to minimize the unexpected introduction of None values into data structures and APIs. Use immutable parameter types when you don't need to modify the input, and be explicit about nullable types to establish clear contracts. ```python # Bad: Unexpectedly modifies input with None values def process_data(progression_futures: list): progression_futures.append(None) # Caller now has List[Optional[...]] # Good: Communicates intent with immutable parameter type def process_data(progression_futures: Sequence): # Create a new collection instead of modifying input result = list(progression_futures) + [None] return result # Good: Be explicit about nullable return values def get_first(items: list[Optional[str]]) -> Optional[str]: return items[0] if items else None ``` When handling potentially null attributes or dictionary keys, use concise safe access patterns: ```python # Verbose and error-prone if "max_version" in kwargs: kwargs.pop("max_version") # Better: Use safe dictionary operations kwargs.pop("max_version", None) # No KeyError if missing # Verbose attribute access name = str(e.name) if hasattr(e, 'name') else str(e) # Better: Use getattr with default name = str(getattr(e, "name", e)) ``` --- ## Use higher-level iterations When working with multiple sequences that need to be combined, prefer higher-level iteration abstractions over nested loops. This improves code readability, reduces nesting depth, and helps prevent logical errors when managing multiple iterative dimensions. For example, instead of writing nested loops: ```python dtypes = [torch.int, torch.long, torch.short] for count_dtype in dtypes: for prob_dtype in dtypes: # process with count_dtype and prob_dtype ``` Use `itertools.product` for a cleaner approach: ```python dtypes = [torch.int, torch.long, torch.short] for count_dtype, prob_dtype in itertools.product(dtypes, repeat=2): # process with count_dtype and prob_dtype ``` Similarly, other Python constructs can simplify iteration patterns: - Use `enumerate` when you need both index and value - Use `zip` to iterate through multiple sequences in parallel - Use comprehensions instead of building collections with loops - Consider `reversed`, `sorted`, or other builtin functions when applicable These higher-level abstractions make algorithmic intent more evident and reduce opportunities for off-by-one errors or incorrect nested logic. --- ## Choose appropriate exceptions Select the proper exception type based on the error scenario to provide clearer error handling and better debugging experience: 1. Use ValueError (TORCH_CHECK_VALUE) when input parameters have invalid values 2. Use RuntimeError (TORCH_CHECK) when user inputs are invalid in ways other than just their values (such as incompatible tensor properties) 3. Use AssertionError (TORCH_CHECK_ASSERT) for internal invariant violations 4. When working with C/Python API boundaries, explicitly check for null pointers and throw appropriate exceptions Example: ```cpp // For invalid parameter values TORCH_CHECK_VALUE( at::isFloatingType(count.scalar_type()), "binomial only supports floating-point dtypes for count, got: ", count.scalar_type()); // For other input validation TORCH_CHECK( indices.is_pinned() == values.is_pinned(), "memory pinning of indices must match memory pinning of values"); // For internal invariants TORCH_INTERNAL_ASSERT(r.idx == 0, "Unexpected parser result"); // For C API null checks PyObject* tuple = PyTuple_New(2); if (!tuple) { throw python_error(); } ``` Using appropriate exception types helps users better understand and handle errors, improves API clarity, and facilitates more effective debugging. Proper error messages that describe the problem and expected behavior enable users to quickly identify and fix issues. --- ## Normalize configuration parameters Always normalize configuration inputs (especially environment variables) by removing whitespace and applying consistent case transformation before processing them. This prevents unexpected behaviors caused by insignificant variations in input format. For environment variables: ```python # Good practice env_value = os.environ.get('TORCH_CONFIG_VAR', None) if env_value: env_value = env_value.strip().lower() # Now process with normalized value ``` For configuration dictionaries, make sure keys are properly normalized if case-insensitive matching is required. Additionally: 1. Don't raise errors for unrecognized configuration parameters when they may be valid for other components or backends - skip or ignore them instead. 2. In documentation, maintain proper syntax for environment variables (e.g., `PYTORCH_TUNABLEOP_ENABLED=1` without spaces). 3. Consider configuration granularity - determine whether a global configuration is sufficient or if per-site configuration offers better flexibility for your specific use case. --- ## Check CUDA availability first Always verify CUDA availability before performing CUDA-specific operations to prevent runtime errors when code runs on systems without CUDA support. When working with device-specific code: 1. Add explicit checks with `torch.cuda.is_available()` before any CUDA-specific operations 2. Use appropriate device properties rather than just device names for better cross-platform compatibility 3. Handle device-like parameters consistently using proper abstractions Example: ```python # Bad - may fail on CPU-only systems if torch.cuda.is_current_stream_capturing(): # CUDA-specific code # Good - safely checks CUDA availability first if torch.cuda.is_available() and torch.cuda.is_current_stream_capturing(): # CUDA-specific code # Better device property handling - use specific properties instead of just names device = input_nodes[0].get_device() if device.type == "cuda": # Use specific device properties for hardware identification device_properties = torch.cuda.get_device_properties(device.index) # Use properties like device_properties.major, device_properties.minor, etc. ``` This approach ensures code works reliably across different hardware configurations and gracefully handles CPU-only environments. --- ## Parameterize similar test cases Instead of duplicating test code or using nested loops, use test parameterization to handle multiple test cases efficiently. This improves maintainability, ensures complete coverage, and makes test failures more traceable. Key benefits: - Reduces code duplication - Makes test variations explicit - Easier to add new test cases - Better failure isolation Example: ```python # Instead of: def test_binomial_dtype_error(self): for count_dtype in dtypes: for prob_dtype in dtypes: # test logic... # Use: @parametrize("count_dtype", [torch.int, torch.long, torch.short]) @parametrize("prob_dtype", [torch.int, torch.long, torch.short]) def test_binomial_dtype_error(self, count_dtype, prob_dtype): # test logic... # For multiple configuration parameters: @parametrize("device", (GPU_TYPE, "cpu")) @parametrize("format", ("binary", "unpacked")) @parametrize("dynamic", (False, True)) def test_basic(self, device: str, format: str, dynamic: bool): # test logic... ``` --- ## Preserve API compatibility When modifying existing APIs, always prioritize backward compatibility to avoid breaking client code. Before changing API signatures, function names, or return types, first consider the impact on existing consumers. If an API needs new functionality: 1. Add new functions rather than modifying existing ones 2. Mark old functions as deprecated before eventual removal 3. Document migration paths clearly For new APIs, consider future compatibility: - Avoid prematurely exposing implementation details with public visibility markers (like `C10_API`) - Only expose interfaces as public when there's clear evidence they need external access Example from the discussions: ```cpp // Instead of changing an existing function signature: // TORCH_API DLManagedTensor* toDLPack(const Tensor& src); // -> TORCH_API DLManagedTensorVersioned* toDLPack(const Tensor& src); // Prefer adding a new function while preserving the original: TORCH_API DLManagedTensor* toDLPack(const Tensor& src); // Maintain original TORCH_API DLManagedTensorVersioned* toDLPackV2(const Tensor& src); // Add new version ``` This approach ensures libraries using your API can upgrade on their own timeline and prevents unexpected runtime failures. --- ## Device-agnostic acceleration code Avoid hardcoding specific device types like 'cuda' in AI code. Instead, use device-agnostic approaches such as device type variables or accelerator detection functions. This ensures code runs efficiently across different hardware accelerators (CUDA, ROCm, XPU, etc.) without modification. Examples: ```python # Instead of this: x = torch.randn(100, 100, device='cuda') # Do this: x = torch.randn(100, 100, device=GPU_TYPE) # Or for more dynamic detection: device = torch.accelerator.current_accelerator().type if torch.accelerator.current_accelerator() else "cpu" x = torch.randn(100, 100, device=device) ``` This approach helps maintain compatibility with various AI hardware acceleration platforms and simplifies testing across multiple device types. For common test cases, prefer using constants like `GPU_TYPE` defined in testing utilities, and for production code, use the accelerator API to detect available devices at runtime. --- ## Design for compatibility When evolving APIs, prioritize backward compatibility to minimize disruption for existing users. Add new functionality using default arguments rather than creating overloaded methods that could cause ABI compatibility issues. For example: ```cpp // Prefer this: void set_device(DeviceIndex device, bool force = false); // Over this: void set_device(DeviceIndex device); void set_device(DeviceIndex device, bool force); ``` When introducing version-dependent features, implement appropriate version checks and fallbacks: ```cpp #if defined(CUDA_VERSION) && (CUDA_VERSION >= 12050) // Use newer API version #else // Fallback implementation for older versions #endif ``` Keep internal implementation details hidden from public-facing interfaces by clearly distinguishing between public APIs and internal functionality. For evolving ABIs, provide transition mechanisms that support both old and new versions simultaneously, allowing consumers to opt into newer versions explicitly while maintaining backward compatibility. --- ## Prefer HINTS in CMake When configuring library searches in CMake, use `HINTS` instead of `PATHS` when you want to prioritize specific locations before falling back to system defaults. `HINTS` are searched before default paths, while `PATHS` are searched after default paths. This ensures that user-specified or environment-provided paths are checked first, making dependency resolution more predictable. Include common path suffixes to improve the robustness of library discovery: ```cmake find_library(NVSHMEM_HOST_LIB # In pip install case, the lib suffix is `.so.3` instead of `.so` NAMES nvshmem_host nvshmem_host.so.3 HINTS $ENV{NVSHMEM_HOME} ${NVSHMEM_PY_DIR} PATH_SUFFIXES lib lib64 cuda/lib cuda/lib64 lib/x64 DOC "The location of NVSHMEM host library.") ``` This approach creates a more reliable search order: 1. First check HINTS locations with their suffixes 2. Then check standard system locations 3. Finally check PATHS locations if specified Using this pattern helps avoid unexpected library resolution and ensures dependencies are found in the correct locations, especially in complex build environments with multiple library versions. --- ## Purpose-revealing identifier names Choose identifier names that clearly reveal their purpose and behavior. Names should be specific, descriptive, and self-explanatory: - **Function names** should include verbs that indicate the action being performed or a question being answered (e.g., use `is_consistent()` rather than `consistency()`) - **Class names** should reflect the nature and purpose of the class (e.g., `VersionString` is better than generic `VersionParser`) - **Method and variable names** should be descriptive enough that comments aren't needed to explain their purpose Avoid vague or overly generic names that don't communicate their specific role. When reviewing code, ask "Does this name clearly explain what it does or represents?" Example: ```python # Less clear: def contains_ungroupable(node): # Implementation... # More clear: def contains_gemm_like(node): # Implementation... ``` This naming approach reduces cognitive load for readers and makes code more maintainable over time by making its purpose immediately evident. --- ## Reduce code duplication Eliminate repeated code patterns by using appropriate abstraction techniques. This improves readability, reduces maintenance burden, and minimizes the risk of inconsistencies when changes are needed. Consider these approaches: 1. **Use templates for similar functions**: ```cpp // Instead of multiple similar functions like: bool use_mkldnn_bf16_matmul(...) { ... } bool use_mkldnn_fp16_matmul(...) { ... } bool use_mkldnn_bf32_matmul(...) { ... } // Use a template: template bool use_mkldnn_matmul(...); ``` 2. **Extract repeated logic into helper functions**: ```cpp // Instead of duplicating checking logic: if (condition_for_iv) { // many lines of validation logic for iv } if (condition_for_src_iv) { // same validation logic repeated for src_iv } // Create a helper function: void validateIValue(const IValue& iv) { // validation logic in one place } ``` 3. **Use modern iteration patterns**: ```cpp // Instead of manual indexing: size_t i = 0; for (const auto& node : graph_->nodes()) { LOG(INFO) << "Node #" << i << ": " << node.toString(); i++; } // Use enumerate for cleaner code: for (const auto&& [i, node] : c10::enumerate(graph_->nodes())) { LOG(INFO) << "Node #" << i << ": " << node.toString(); } ``` By consistently applying these patterns, you'll create more maintainable code that's easier to understand and modify. --- ## Thread context management Always explicitly set required thread context and state rather than assuming inheritance from parent threads or other concurrent processes. In multithreaded and distributed environments, assumptions about shared state can lead to subtle bugs, race conditions, and incorrect behavior. For example, when setting device context in a multithreaded environment: ```python # Incorrect: Assuming device context is inherited def _pin_memory_loop(in_queue, out_queue, done_event, device): # This might not work as expected in a different thread process_data(in_queue) # Correct: Explicitly set device context in each thread def _pin_memory_loop(in_queue, out_queue, done_event, device): # Set device context explicitly in this thread torch.accelerator.set_device_index(torch.accelerator.current_device_index()) process_data(in_queue) ``` Similarly, be careful about assumptions regarding process groups in distributed computing. Each component should clearly document and validate its threading model and required context. Use proper synchronization mechanisms like barriers when operations across threads depend on each other's completion. --- ## Structure for readability Structure code to maximize readability by reducing unnecessary complexity. Use early returns to minimize nesting levels, move invariant conditions outside of loops, and replace magic numbers with named constants. Example - Replace deeply nested conditions: ```python # Instead of this: def estimate_flops(self) -> int | None: if isinstance(self, ExternKernel): if op is not None: # Deep logic here pass return None # Prefer this: def estimate_flops(self) -> int | None: if not isinstance(self, ExternKernel) or op is None: return None # Logic continues at a single nesting level ``` Similarly, when a condition inside a loop doesn't change between iterations, move it outside: ```python # Instead of checking the same condition in each iteration for i, future in enumerate(self._progression_futures): if self._post_compile_data and future.done(): # Logic here # Check invariant conditions before the loop if self._post_compile_data: for i, future in enumerate(self._progression_futures): if future.done(): # Logic here ``` And always use named constants instead of unexplained numbers: ```python # Instead of: for i, (gb_type, info) in enumerate(sorted(gb_types.items()), 1001): # Logic using magic number 1001 # Use: START_ID = 1001 # Base ID for graph break types for i, (gb_type, info) in enumerate(sorted(gb_types.items()), START_ID): # Logic using named constant ``` --- ## Hardware acceleration considerations When implementing hardware-accelerated operations for AI models, ensure support for the latest architectures while considering determinism requirements. 1. Keep architecture support up-to-date: Regularly update code to support new hardware architectures (like the latest CUDA architectures for NVIDIA GPUs or optimized paths for specialized hardware). ```cpp // Example: Ensure architecture lists include the latest generations // Don't forget to add new architectures like Blackwell elseif(${arch_name} STREQUAL "Ampere") set(arch_bin 8.0) set(arch_ptx 8.0) elseif(${arch_name} STREQUAL "Hopper") set(arch_bin 9.0) set(arch_ptx 9.0) elseif(${arch_name} STREQUAL "Blackwell") set(arch_bin 10.0) set(arch_ptx 10.0) ``` 2. Consider determinism: When implementing operations with atomic updates (like pooling operations), evaluate if they're deterministic. If not, provide alternatives or mark them appropriately for users requiring deterministic algorithms. ```cpp // When implementing operations with potential non-determinism: // 1. Document the non-deterministic behavior // 2. Consider providing a deterministic alternative implementation // 3. Add appropriate flags for torch.use_deterministic_algorithms() // Example for pooling operations: if (at::globalContext().deterministicAlgorithms() && requires_deterministic_implementation) { // Use deterministic implementation (might be slower) } else { // Use potentially faster non-deterministic implementation with atomics AtomicType::atomic_add(...); } ``` Hardware-optimized implementations significantly impact AI model performance, but must be balanced with requirements for reproducibility in research and production deployments. --- ## Actionable error messages When writing error messages in PyTorch code, include not only what went wrong but also clear guidance on how to fix the issue. This helps users quickly understand and resolve problems without digging through documentation. Example from tensor device operations: ```cpp // Poor error message: TORCH_CHECK(false, "Cannot move tensor between devices"); // Better error message with remediation: TORCH_CHECK( !force_move, "cannot move tensor from ", data.device(), " to ", device, " without copying. Set copy=True is needed."); ``` This practice is especially important for operations that have non-obvious requirements or constraints, such as tensor movement between devices, shape transformations, or operations with specific dtype requirements. By providing actionable guidance directly in error messages, you improve the developer experience and reduce support burden. --- ## Descriptive unambiguous names Always use descriptive variable names that clearly indicate their purpose without requiring readers to check call sites or implementation details. Avoid single-letter variables like `t` or vague abbreviations, especially in public interfaces and open-source code. Additionally, ensure clear distinction between similarly named variables, particularly when distinguishing between member variables and local variables with related purposes. Bad example: ```cpp void LayoutManager::assert_no_overlapping_storages(const Node& node, size_t t) { // t is unclear - does it mean time, temporary, or something else? } class AliasAnalyzer { private: std::set aliases_; void someMethod() { std::set aliases; // Confusing similarity to member variable // Code using both aliases_ and aliases } }; ``` Good example: ```cpp void LayoutManager::assert_no_overlapping_storages(const Node& node, size_t nodeIdx) { // Clear that this refers to a node index } class AliasAnalyzer { private: std::set finalized_aliases_; // More descriptive name void someMethod() { std::set current_aliases; // Clearly distinct from member variable // Code using both finalized_aliases_ and current_aliases } }; ``` --- ## Cross-platform API design rules Design public APIs to work seamlessly across different programming languages and platforms. Follow these key principles: 1. Use platform-agnostic types in public interfaces: - Prefer `int` over `size_t` for array sizes and indices - Avoid unsigned types that don't translate well to other languages - Use explicit size types (int32_t, int64_t) when specific sizes are required 2. Add proper binding annotations for cross-language support: ```cpp class CV_EXPORTS_W MyClass { public: CV_WRAP void process(int size); // Not size_t CV_WRAP_AS(processBytes) Mat process(InputArray data); // Alias for clarity }; ``` 3. Avoid passing language-specific objects through plugin/module boundaries: - Don't pass STL containers or C++ objects through plugin APIs - Use C-style interfaces or abstract base classes for plugin APIs - Consider providing factory functions for complex objects 4. Maintain binary compatibility: - Don't modify existing function signatures - Create new overloads or functions for extended functionality - Document API version changes clearly Following these guidelines ensures your API works reliably across Python, Java, and C++ while maintaining long-term stability. --- ## Optimize memory usage Limit memory consumption in performance-critical paths by conditionally creating large data structures or deferring allocation until needed. Large tracking structures, debug information, and memory-intensive operations should be guarded by configuration flags to prevent them from impacting performance in production environments. For example, when implementing debug features, wrap memory-intensive operations in conditional blocks: ```cpp // Before: Always creates large data structure for (const auto& [v, lifetime] : lifetimes_) { for (const auto t : c10::irange(lifetime.start, lifetime.end + 1)) { alive_values_at_time_[t].emplace_back(v); } } // After: Only create when debug mode is enabled #ifdef DEBUG_MODE for (const auto& [v, lifetime] : lifetimes_) { for (const auto t : c10::irange(lifetime.start, lifetime.end + 1)) { alive_values_at_time_[t].emplace_back(v); } } #endif ``` Additionally, use appropriate resource management patterns (RAII, smart pointers) to ensure efficient memory utilization and prevent leaks in performance-sensitive code. When working with external APIs like the Python C API, maintain correct reference counting to avoid memory leaks that can gradually degrade performance over time. In memory-constrained environments like GPU computing, these optimizations can prevent out-of-memory errors and significantly improve overall system performance. --- ## Consistent code organization Follow consistent code organization patterns: 1. Place static definitions in .cpp files rather than headers to prevent duplicate definitions when included in multiple compilation units: ```cpp // Avoid in header (.hpp): static HeartbeatMonitor* get() { static HeartbeatMonitor instance; return &instance; } // Prefer in implementation (.cpp): HeartbeatMonitor* HeartbeatMonitor::get() { static HeartbeatMonitor instance; return &instance; } ``` 2. Explicitly define class semantics using appropriate macros and default specifications: ```cpp class BiasHandler { C10_DISABLE_COPY_AND_ASSIGN(BiasHandler); BiasHandler(BiasHandler&&) = default; BiasHandler& operator=(BiasHandler&&) = default; // Class implementation... }; ``` 3. Maintain consistent implementation patterns across related components (e.g., use class-based or function-based implementations consistently for similar functionality). When extending existing code, follow the established patterns from the CPU implementation or related components. --- ## Centralize configuration detection Always use centralized configuration detection mechanisms (like CMake finder modules) instead of hardcoding paths or environment variables. This approach ensures compatibility across different installation methods and environments. When integrating with external libraries or tools: 1. Prefer creating dedicated finder modules (e.g., `findXXX.cmake`) that can detect installations in multiple locations 2. Avoid directly exporting environment variables in scripts that may not be universally applicable 3. Implement robust path resolution that works consistently across build environments 4. Validate that paths exist before using them in critical operations For example, instead of hardcoding: ```bash export NVSHMEM_HOME=/usr/local ``` Create a CMake finder module that can handle multiple installation scenarios: ```cmake # findNVSHMEM.cmake example find_path(NVSHMEM_INCLUDE_DIR nvshmem.h PATHS ${NVSHMEM_HOME}/include /usr/local/include $ENV{CONDA_PREFIX}/include ) if(NVSHMEM_INCLUDE_DIR) get_filename_component(NVSHMEM_HOME ${NVSHMEM_INCLUDE_DIR} DIRECTORY) endif() ``` This approach ensures your build system can adapt to different installation methods (pip, system packages, custom paths) without requiring manual configuration changes. --- ## Choose data structures wisely When designing algorithms, select data structures that accommodate all possible scenarios, not just the common case. For static analysis algorithms where certainty isn't guaranteed, prefer collections that can represent one-to-many relationships even when most instances will contain only one element. This prevents having to redesign your algorithm later when edge cases are discovered. For example, instead of using: ```cpp c10::FastMap aliases_; // One-to-one mapping ``` Use a structure that supports potential multiple relationships: ```cpp c10::FastMap> aliases_; // One-to-many mapping ``` This approach is particularly important in static analysis, compiler optimizations, and other scenarios where the algorithm must account for all possible execution paths, even if most runtime instances follow a simpler pattern. --- ## Clear API contracts Design APIs with clear contracts that behave exactly as their names and signatures suggest. Functions should do precisely what they claim to do without surprising side effects or hidden behaviors. Key principles: - Function behavior must strictly align with its name and signature - Prefer simplified interfaces that abstract implementation details - Be explicit about parameter requirements and behaviors - Raise errors for invalid operations rather than using fallback paths - Use sensible defaults that follow established conventions **Example of poor design:** ```cpp // Confusing API with unclear behavior bool initializeContextFromVA(VADisplay display, bool tryInterop) { // Uses a different display if provided one doesn't work // Silently falls back to non-interop mode if tryInterop fails // Returns success even when not using the requested display } ``` **Improved design:** ```cpp // Clear contract, predictable behavior bool initializeContextFromVA(VADisplay display) { // Only initializes with the exact display provided // Throws exception with clear message if initialization fails // Returns true only when successfully initialized with given display } ``` Remember to document any special parameter handling. If your function treats certain values (like Point(0,0)) specially, make this explicit in both the function signature (with default parameters) and documentation. When extending existing APIs, maintain consistency with established patterns in the codebase. --- ## Eliminate redundant operations Avoid unnecessary operations that can impact performance. This includes: 1. Redundant data transformations: - Load data directly from sources instead of creating temporary copies - Reuse existing transformed data rather than recreating it - Avoid unnecessary type conversions 2. Minimize attribute lookups and string operations: - Cache frequently accessed attributes - Avoid redundant string conversions, especially in logging Example of improvements: ```python # Bad - Unnecessary string conversion and temporary storage content = path.read_text(encoding="utf-8") pyproject = tomllib.loads(content) # Good - Direct loading pyproject = tomllib.loads(path.read_text(encoding="utf-8")) # Bad - Redundant str conversion in logging log.debug("Selected choice: %s", str(node)) # Good - Let logging handle the conversion log.debug("Selected choice: %s", node) ``` These optimizations are particularly important in performance-critical paths and frequently executed code sections. --- ## Modular configuration design Configuration systems should be designed with modularity and clarity in mind. When creating configuration classes or mechanisms: 1. **Separate generic from specific configurations**: Organize configuration options by their scope and applicability. Use class hierarchies or namespaces to isolate domain-specific settings from generic ones. ```cpp // Good practice - clear separation of concerns class AcceleratorAllocatorConfig { // Common settings applicable to all accelerators }; class CUDAAllocatorConfig : public AcceleratorAllocatorConfig { // CUDA-specific settings }; ``` 2. **Use descriptive, consistent naming conventions**: Configuration option names should clearly indicate their purpose and scope. - Avoid device-specific terms in generic interfaces (e.g., use `device_malloc` not `cudamalloc`) - Use consistent prefixes to group related options (e.g., `pinned_` for pinned memory settings) 3. **Document all configuration options**: Each option should have clear documentation explaining its purpose, valid values, and implications. 4. **Design for extensibility**: Implement hook mechanisms that allow domain-specific configurations to be integrated with generic ones. 5. **Propagate build-time configurations**: When generating configuration files (e.g., from .cmake.in templates), ensure build-time choices are properly encoded for downstream consumers. These practices improve maintainability by making configuration systems more intuitive, better documented, and easier to extend for new devices or backends. --- ## Code for readability Prioritize human readability when writing code. Split complex expressions into steps with meaningful variable names. Extract repeated logic into well-named functions. Avoid magic numbers - derive values from existing structures or use named constants. Simplify control flow by reducing nesting levels and using early returns. ```cpp // Instead of: if (VP8_STATUS_OK == WebPGetFeatures(header, sizeof(header), &features)) { // Many lines of nested code } // Prefer: if (VP8_STATUS_OK < WebPGetFeatures(header, sizeof(header), &features)) return false; // For complex conditions, split into steps: // Instead of: if(cv::gapi::getCompileArg>(compileArgs).has_value()) { // ... // Prefer: auto workload = cv::gapi::getCompileArg>(compileArgs); if(workload.has_value()) { // ... // Instead of magic numbers: const Mat points_mat = Mat(Size(6, 24), CV_32F, &points_data); // Prefer: const size_t channels = 6; // 3 coordinates + 3 color values const size_t pointCount = sizeof(points_data)/(channels*sizeof(float)); const Mat points_mat = Mat(Size(channels, pointCount), CV_32F, &points_data); ``` --- ## Use descriptive names Choose names that clearly communicate purpose and meaning rather than using abbreviations or unclear terms. Names should be self-documenting and make the code's intent obvious without requiring additional context. Avoid abbreviations that obscure meaning. Instead of `ds` use `downscale`, instead of `audioData` and `microphone` use `rawAudio` and `audioMetadata` to clarify their distinct purposes. Replace computed expressions with semantic variable names. Instead of repeatedly using `width / scale`, define clear variables like `inputSize` and `outputSize`. Make struct and class names descriptive of their actual purpose. Instead of generic names like `SmolModelDataV2`, use specific names like `DrivingModelData` that indicate what the data represents. Example: ```cpp // Poor naming - unclear purpose void OS04C10::OS04C10_IFE_ds_override() { ... } struct SmolModelDataV2 { ... } // Better naming - clear and descriptive void OS04C10::ife_downscale_configure() { ... } struct DrivingModelData { ... } ``` This approach makes code more maintainable and reduces the need for developers to reference other files or documentation to understand what identifiers represent. --- ## Document configuration decisions Always document configuration decisions in package metadata files like `pyproject.toml` with clear comments, especially when: 1. Using deprecated formats due to technical constraints 2. Setting version constraints that may affect compatibility 3. Making decisions that might need revisiting in the future When configuration decisions deviate from best practices, include the reasoning and any relevant links or references. Additionally, implement linters to ensure consistency between related configuration sections (e.g., Python version constraints and classifiers). Example: ```toml [project] # TODO: change to `license = "BSD-3-Clause"` and enable PEP 639 after pinning setuptools>=77 # FIXME: As of 2025.06.20, it is hard to ensure the minimum version of setuptools in our CI environment. # TOML-table-based license deprecated in setuptools>=77, and the deprecation warning will be changed # to an error on 2026.02.18. See also: https://github.com/pypa/setuptools/issues/4903 license = { text = "BSD-3-Clause" } requires-python = ">=3.9" # also update classifiers when changing this ``` This approach ensures that future developers understand the context behind configuration choices and helps maintain consistency across the codebase. It also creates clear reminders for revisiting temporary workarounds as technical constraints evolve. --- ## Initialize and validate values Always initialize variables with sensible default values and validate inputs to prevent null reference errors and undefined behavior. This includes three key practices: 1. **Initialize with defaults**: Set initial values in constructors to avoid uninitialized state issues, especially when methods may be called before updates occur. 2. **Validate inputs**: Check that input parameters meet expected formats and constraints before processing, even if you don't validate the full domain. 3. **Handle missing values**: Provide explicit fallback behavior when parameters or configuration values might be missing or deleted. Example from the codebase: ```python # Good: Initialize with default value def __init__(self): self.avg_dt = MovingAverage(100) self.avg_dt.add_value(self._interval) # Prevents uninitialized state # Good: Validate input format def setEsimProfile(iccid: str): # Validate input is valid ICCID format if not is_valid_iccid(iccid): raise ValueError("Invalid ICCID format") HARDWARE.get_sim_lpa().switch_profile(iccid) # Good: Handle missing parameters with fallback def read_param(self): param_value = self.params.get('LongitudinalPersonality') if param_value is not None: self.personality = param_value else: self.personality = log.LongitudinalPersonality.standard # Fallback ``` This prevents runtime errors from null references, uninitialized variables, and invalid inputs while ensuring predictable behavior. --- ## Hardware compatibility patterns Implement proper hardware compatibility patterns when working with different GPU backends and AI frameworks. Many AI applications need to support multiple hardware platforms (NVIDIA CUDA, AMD ROCm, Intel XPU, Moore Threads, DirectML, ZLUDA) which have different capabilities and limitations. Key practices: 1. **Device detection and conditional logic**: Check device capabilities before using specific operations 2. **Graceful fallbacks**: Provide alternative implementations when hardware doesn't support certain operations 3. **Import isolation**: Use helper functions to avoid breaking hardware-specific initialization (like CUDA malloc) 4. **Hardware-specific optimizations**: Apply backend-specific settings while maintaining compatibility Example implementation: ```python # Device-specific handling with fallbacks if image.device.type == 'musa': # Moore Threads GPU doesn't support bicubic with antialias image = image.cpu() image = torch.nn.functional.interpolate(image, size=scale_size, mode="bicubic", antialias=True) image = image.to('musa') else: image = torch.nn.functional.interpolate(image, size=scale_size, mode="bicubic", antialias=True) # Hardware detection with specific optimizations if "[ZLUDA]" in torch_device_name: torch.backends.cudnn.enabled = False torch.backends.cuda.enable_flash_sdp(False) torch.backends.cuda.enable_math_sdp(True) torch.backends.cuda.enable_mem_efficient_sdp(False) # DirectML-specific tensor operations if comfy.model_management.is_directml_enabled(): latents_ubyte = latents_ubyte.to(dtype=torch.uint8) latents_ubyte = latents_ubyte.to(device="cpu", dtype=torch.uint8, non_blocking=...) ``` This approach ensures AI applications work reliably across different hardware while taking advantage of platform-specific optimizations where available. --- ## Reuse existing algorithms Before implementing common algorithms or utilities, check if the codebase already contains an appropriate implementation. Reusing existing, tested code reduces bugs, improves maintainability, and often provides better performance characteristics. For example, instead of reimplementing a counting function: ```cpp // Don't reimplement existing functionality template size_t count_leading_zeros(T val) { // Custom implementation... } ``` Use the existing implementation: ```cpp // Do use existing implementations #include // Then use LeadingZerosCounter directly ``` Similarly, when selecting algorithms (like random number generators), evaluate existing options based on required properties such as period length or performance characteristics. For instance, prefer `VSL_BRNG_PHILOX4X32X10` or `VSL_BRNG_MT19937` over simpler generators if statistical quality is important, rather than implementing custom variants. This principle helps maintain code consistency, avoids duplication of effort, and leverages optimizations already present in established implementations. --- ## Pin dependency versions Always pin specific versions of dependencies, tools, and commits in configuration files to ensure consistent behavior across environments and deployments. When pinning versions, include comments explaining the reasoning behind the specific version choice. This practice prevents unexpected breakages from automatic updates and ensures all team members and deployment environments use identical dependency versions. When allowing version overrides through parameters, maintain the pinned version as the default fallback. Example: ```bash # Pin specific versions with explanatory comments brew "llvm@19" # pinned for tinygrad compatibility # In build scripts, allow override but keep pinned default COMMIT="${1:-66030a7de62c9e1ee8ab30a1d657a740333bb4f2}" # default pinned commit # Version numbers should be incremented properly export AGNOS_VERSION="12" # increment ensures all devices run same version ``` This approach maintains stability while allowing flexibility when needed, and the comments help future maintainers understand the rationale behind version choices. --- ## AI hardware platform support AI applications must properly handle different GPU platforms (NVIDIA CUDA, AMD ROCm, Iluvatar Corex, etc.) through both build-time configuration and runtime capability detection. This ensures models can run efficiently across diverse hardware environments. Build-time considerations: - Use parameterized builds to support different PyTorch variants for target platforms - Configure appropriate package indices for platform-specific dependencies Runtime considerations: - Implement capability checks before using platform-specific features - Provide graceful fallbacks when advanced features aren't supported - Add platform detection logic to automatically adjust behavior Example implementation: ```python # Runtime capability check def cuda_malloc_supported(): # Check if platform supports cudaMallocAsync if platform_is_iluvatar(): return False return True # Build-time configuration # docker build --build-arg VARIANT=cu126 . # NVIDIA # docker build --build-arg VARIANT=rocm6.2 . # AMD # python main.py --disable-cuda-malloc # Iluvatar fallback ``` This approach ensures AI applications remain portable and performant across different hardware platforms while leveraging platform-specific optimizations when available. --- ## Use OpenCV error mechanisms Always use OpenCV's built-in error handling mechanisms instead of C++ exceptions or custom error handling. This ensures consistent error handling across the codebase and proper integration with OpenCV's error handling infrastructure. Key guidelines: 1. Use CV_Assert() for input validation and preconditions 2. Use CV_Error() for runtime errors 3. Use CV_LOG_WARNING() for non-fatal issues 4. Return status codes instead of throwing exceptions Example: ```cpp void processImage(InputArray src, OutputArray dst, int param) { // Input validation CV_Assert(src.dims() <= 2 && src.channels() <= 4); CV_Assert(param > 0 && param < 100); // Runtime error handling if (!src.isContinuous()) CV_Error(Error::StsBadArg, "Input array must be continuous"); // Warning for non-fatal issues if (param < 10) CV_LOG_WARNING(NULL, "Parameter value < 10 may reduce accuracy"); // Return false instead of throwing if (!processData()) return false; } ``` --- ## Optimize memory allocation patterns Prefer efficient memory allocation patterns to improve performance. Key practices: 1. Use RAII containers (like Mat) instead of raw pointers to prevent memory leaks 2. Pre-allocate containers when size is known 3. Use stack allocation for small, fixed-size objects 4. Avoid unnecessary dynamic allocation Example - Before: ```cpp // Inefficient allocation patterns char* get_raw_data() { return new char[size]; // Raw pointer, potential memory leak } std::vector img_vec; img_vec.push_back(img); // Potential reallocation fcvPyramidLevel_v2 *framePyr = new fcvPyramidLevel_v2[2]; // Unnecessary heap allocation ``` Example - After: ```cpp // Efficient allocation patterns Mat get_data() { return Mat(size); // RAII handles cleanup } std::vector img_vec(1, img); // Pre-allocated size fcvPyramidLevel_v2 framePyr[2]; // Stack allocation for small arrays ``` Benefits: - Prevents memory leaks - Reduces allocation overhead - Improves cache utilization - More predictable performance --- ## Prefer explicit readable code Write code that prioritizes readability and explicitness over cleverness or brevity. This includes several key practices: **Import Organization**: Follow standard import ordering - stdlib and third-party imports first, then openpilot imports after a blank line: ```python import os import threading import numpy as np from openpilot.common.params import Params from openpilot.selfdrive.ui.ui_state import ui_state ``` **Explicit Conditionals**: Use clear if-elif chains instead of complex conditional expressions: ```python # Prefer this: if self.CP.carFingerprint in FCEV_CAR: ret.gas = cp.vl["ACCELERATOR"]["ACCELERATOR_PEDAL"] / 254. elif self.CP.carFingerprint in HYBRID_CAR: ret.gas = cp.vl["E_EMS11"]["CR_Vcu_AccPedDep_Pos"] / 254. else: ret.gas = cp.vl["E_EMS11"]["Accel_Pedal_Pos"] / 254. # Over this: gas_sig = "Accel_Pedal_Pos" if self.CP.carFingerprint in EV_CAR else \ "ACCELERATOR_PEDAL" if self.CP.carFingerprint in FCEV_CAR else \ "CR_Vcu_AccPedDep_Pos" ``` **Simple Variable Assignment**: Avoid walrus operators and complex expressions when simple two-line assignments are clearer: ```python # Prefer this: events_changed = self.events.names != self.events_prev if events_changed: # Over this: if events_changed := (self.events.names != self.events_prev): ``` **Meaningful Variable Names**: Use descriptive variables instead of magic numbers or complex expressions: ```python # Prefer this: counter = int(CS.sccm_right_stalk["SCCM_rightStalkCounter"]) can_sends.append(self.tesla_can.right_stalk_press(counter + 1, 1)) can_sends.append(self.tesla_can.right_stalk_press(counter + 2, 0)) # Over this: counter = int(CS.sccm_right_stalk["SCCM_rightStalkCounter"] + 1) % 16 can_sends.append(self.tesla_can.right_stalk_press(counter, 1)) can_sends.append(self.tesla_can.right_stalk_press((counter + 1) % 16, 0)) ``` The goal is to write code that other developers can quickly understand without having to decode complex expressions or trace through clever logic. --- ## Prevent path traversal Always validate and sanitize file paths from user input to prevent directory traversal attacks. Malicious actors can use path manipulation techniques like `../../../` sequences or absolute paths to access files outside intended directories, potentially overwriting critical system files or accessing sensitive data. Key validation steps: 1. Sanitize input by removing or rejecting dangerous path components 2. Resolve the full absolute path and verify it stays within allowed boundaries 3. Validate both directory and filename components separately Example of vulnerable code: ```python # BAD: No validation allows path traversal model_name = user_input # Could be "../../../../passwd" file_path = os.path.join(models_dir, model_sub_directory, model_name) ``` Example of secure implementation: ```python # GOOD: Validate filename and check final path def validate_filename(filename): # Reject dangerous characters and sequences if '..' in filename or '/' in filename or '\\' in filename: return False return True if not validate_filename(model_name): raise ValueError("Invalid filename") file_path = os.path.join(models_dir, model_sub_directory, model_name) resolved_path = os.path.abspath(file_path) # Ensure final path is within allowed directory if not resolved_path.startswith(os.path.abspath(models_dir)): raise ValueError("Path outside allowed directory") ``` This prevents attackers from writing malicious code to locations like `custom_nodes/*/.__init__.py` or accessing sensitive system directories. --- ## Use descriptive names Choose descriptive, self-documenting names for constants, functions, parameters, and types that clearly communicate their purpose and meaning. Avoid magic numbers, generic strings, and ambiguous identifiers that require additional context to understand. Replace magic values with named constants: ```python # Instead of: win32event.WaitForSingleObject(hProcess, 10 * 1000) # Use: TEN_SECONDS_MS = 10 * 1000 win32event.WaitForSingleObject(hProcess, TEN_SECONDS_MS) ``` Use semantic constants instead of magic strings: ```python # Instead of: {"source": ("*", {})} # Use: {"source": (node_typing.IO.ANY, {})} ``` Choose accurate function names that reflect their actual behavior: ```python # Instead of: def init_builtin_custom_nodes(): # Use: def init_builtin_extra_nodes(): ``` Use specific type annotations that communicate intent: ```python # Instead of: def filter_files_content_types(files: List[str], content_types: List[str]) -> List[str]: # Use: def filter_files_content_types(files: List[str], content_types: Literal["image", "video", "audio"]) -> List[str]: ``` This practice makes code self-documenting, reduces the need for comments, and helps prevent misunderstandings about the code's purpose and behavior. --- ## Explicit error propagation Functions should raise exceptions with meaningful messages instead of returning False, None, or silently catching all exceptions. This allows calling code to properly understand what went wrong and take appropriate action. **Key principles:** - Raise specific exceptions instead of returning error indicators like False or None - Provide descriptive error messages that help diagnose the problem - Avoid catching and silently swallowing all exceptions unless absolutely necessary - Ensure calling code can distinguish between success and failure states **Example of problematic pattern:** ```python def path_is_low_integrity_writable(path): result = subprocess.run([ICACLS_PATH, path], capture_output=True, text=True) if result.returncode != 0: # Silent failure - calling code doesn't know what went wrong return False return does_permit_low_integrity_write(result.stdout) ``` **Improved approach:** ```python def path_is_low_integrity_writable(path): result = subprocess.run([ICACLS_PATH, path], capture_output=True, text=True) if result.returncode != 0: raise PermissionError(f"Failed to check ACL for path {path}: {result.stderr}") return does_permit_low_integrity_write(result.stdout) ``` **Additional considerations:** - Use appropriate exception types (ValueError, FileNotFoundError, etc.) rather than generic Exception - Document when functions are expected to return ExecutionBlocker vs raise exceptions - Track both success and failure states explicitly in execution flows - Add logging for error conditions even when exceptions are raised --- ## Document complex code Add explanatory comments or docstrings for complex, specialized, or non-obvious code that may not be immediately clear to other developers. This includes magic constants, platform-specific operations, advanced APIs, and implementation decisions with specific reasoning. Key areas requiring documentation: - Magic numbers or constants with their meaning and purpose - Platform-specific or specialized API usage (like win32 operations) - Functions using advanced or uncommon techniques - Implementation choices with specific technical reasoning - File-level docstrings for modules dealing with specialized domains Example for magic constants: ```python # Windows Low Integrity Level SID - restricts process permissions for sandboxing LOW_INTEGRITY_SID_STRING = "S-1-16-4096" ``` Example for specialized functions: ```python def set_process_integrity_level_to_low(): """ Set the current process to run at a low integrity level. This restricts the process's permissions, creating a sandboxed environment to limit potential damage if compromised. """ ``` Example for implementation decisions: ```python # Use .tmp suffix during download to prevent incomplete state if interrupted # Otherwise CTRL+C during download leaves ComfyUI thinking frontend is installed tmp_path = web_root + ".tmp" ``` This ensures code maintainability and helps other developers understand the reasoning behind complex or specialized implementations. --- ## Validate tensor dimensions When implementing AI model inference code, always validate tensor dimensions and shapes before manipulating them. Neural network outputs often have complex multi-dimensional structures that require careful handling. Adding explicit dimension checks prevents subtle runtime errors, improves code robustness, and makes debugging easier. Before reshaping tensors or extracting specific values: 1. Check that the tensor has the expected number of dimensions 2. Verify tensor shapes match your expectations 3. Add defensive assertions for critical assumptions Example: ```cpp // Before tensor manipulation, add validation CV_CheckEQ(outs[0].dims, 3, "Expected 3D tensor output"); CV_CheckEQ((outs[0].size[2] == nc + 5 || outs[0].size[2] == nc + 4), true, "Invalid output shape"); // Then proceed with manipulation vector channels; for (int i = 0; i < 3; ++i) { channels.push_back(Mat(output_transposed.size[1], output_transposed.size[2], CV_32F, output_transposed.ptr(i))); } ``` For parameters derived from tensor shapes, consider whether they should be computed or passed as parameters based on the model's architecture. Always document your assumptions about tensor shapes, especially when working with different AI model formats or versions. --- ## Maintain build compatibility When modifying build scripts or configurations, ensure compatibility across all supported environments and properly test changes through CI pipelines. For tools with version-dependent features, add version checks and provide alternative implementations for older versions. Example for CMake version-specific features: ```cmake if(CMAKE_VERSION VERSION_LESS "3.13") # Use older approach for CMake < 3.13 set(PROTOBUF_GENERATE_CPP_APPEND_PATH ON) protobuf_generate_cpp(fw_srcs fw_hdrs ${proto_files}) else() # Use newer approach available in CMake 3.13+ protobuf_generate( APPEND_PATH LANGUAGE cpp IMPORT_DIRS ${Protobuf_IMPORT_DIRS} OUT_VAR fw_srcs PROTOC_EXE ${Protobuf_PROTOC_EXECUTABLE} PROTOS ${proto_files}) # Process the output variables as needed set(fw_hdrs "${fw_srcs}") list(FILTER fw_srcs EXCLUDE REGEX ".+\.h$") list(FILTER fw_hdrs INCLUDE REGEX ".+\.h$") endif() ``` Always reference the specific CI workflow that validates your build changes (e.g., "This change is tested by the workflow at .github/workflows/OCV-PR-4.x-Android-Test.yaml") to demonstrate the build continues to work across all supported platforms and configurations. --- ## use logging over print Replace all `print()` statements with appropriate logging calls using Python's built-in logging module. This applies to debug output, informational messages, and error reporting. Print statements should be reserved only for direct user interaction or when logging infrastructure is not available. Use appropriate logging levels: - `logging.debug()` for debug information - `logging.info()` for general informational messages - `logging.warning()` for warnings - `logging.error()` for error conditions Example transformation: ```python # Instead of: print(f"Error reading version in get_workflow_templates_version: {e}") print("Single LLAMA3_8 for HiDreams") print(mask.shape) # Use: logging.error(f"Error reading version in get_workflow_templates_version: {e}") logging.info("Single LLAMA3_8 for HiDreams") logging.debug(f"Mask shape: {mask.shape}") ``` This ensures consistent log formatting, proper log levels, and enables centralized log management and filtering. Remove debug print statements entirely when they're no longer needed, and ensure you're using Python's standard `logging` module rather than custom logging libraries. --- ## Reusable workflow design {% raw %} Design CI/CD workflows with reusability and clear naming conventions from the start. Use meaningful prefixes that reflect the conceptual purpose (like "trunk" for trunk-based development), and consider future extraction into standalone, parameterized actions when similar functionality might be needed across repositories. For workflow implementation: 1. Choose meaningful, consistent naming conventions 2. Make key values configurable via input parameters 3. Use consistent package management approaches with explicit flags Example: ```yaml name: reusable-build-workflow on: workflow_call: inputs: commit_sha: description: 'Commit SHA to build (leave empty for current HEAD)' required: false type: string prefix: description: 'Tag prefix to use (e.g. trunk)' required: true type: string jobs: build: steps: - name: Set variables id: vars run: | COMMIT_SHA="${{ inputs.commit_sha || github.sha }}" echo "tag_name=${{ inputs.prefix }}/${COMMIT_SHA}" >> $GITHUB_OUTPUT # For package installation, use consistent approach with explicit flags - name: Install dependencies run: pip install cmake --force-reinstall ``` This approach makes workflows more maintainable and enables cross-repository sharing of common CI/CD patterns. {% endraw %} --- ## Optimize container operations Minimize CPU overhead in container operations by using efficient data structure patterns: 1. **Use static containers** for fixed lookup tables or maps that are frequently accessed but rarely changed. This avoids reconstruction overhead on each function call: ```cpp // Inefficient: Recreates map on every function call void handle() { std::unordered_map handler_map = { /* entries */ }; // ... } // Efficient: Creates map once for all calls void handle() { static std::unordered_map handler_map = { /* entries */ }; // ... } ``` 2. **Prefer emplace over insert** for maps and other containers to avoid unnecessary temporary object construction: ```cpp // Less efficient: Creates a temporary pair object args.insert({DNNL_ARG_SRC, dnnl::memory(m1_md, eng, m1.data_ptr())}); // More efficient: Constructs the object in-place args.emplace(DNNL_ARG_SRC, dnnl::memory(m1_md, eng, m1.data_ptr())); ``` These optimizations reduce memory allocations, minimize CPU cycles, and can significantly improve performance in hot code paths or when working with large containers. --- ## Type-appropriate null representation Always use type-appropriate mechanisms to represent the absence of a value. For objects, use default constructors rather than nullptr. For potentially absent values, consider using optional types. For pointers, use null checks before performing operations on them. Examples: - INCORRECT: `bias_md = nullptr;` when `bias_md` is an object type (dnnl::memory::desc) - CORRECT: `bias_md = dnnl::memory::desc();` to represent an "empty" descriptor - INCORRECT: `ncclHeartbeatMonitorThread_ = std::thread(...);` without checking current state - CORRECT: ```cpp // Check nullness before assignment to prevent issues on second call if (!ncclHeartbeatMonitorThread_.joinable()) { ncclHeartbeatMonitorThread_ = std::thread(...); } ``` This practice improves type safety, prevents null pointer dereferences, and creates more maintainable code by using language features designed for representing absence of values. --- ## Use proper assertions Write tests with proper assertions to ensure reliability and maintainability. Follow these guidelines: 1. **Check for empty data** before proceeding with tests to prevent invalid test conditions: ```cpp string path = cvtest::findDataFile("test_image.png"); Mat img = imread(path); ASSERT_FALSE(img.empty()) << "Cannot open test image: " << path; ``` 2. **Use ASSERT_* for critical conditions** that should halt test execution when failed: ```cpp // Use ASSERT_TRUE for file operations and resource initialization ASSERT_TRUE(fs.isOpened()) << "Failed to open file"; // Use EXPECT_* for test validations that shouldn't interrupt the test EXPECT_EQ(dst.cols, 270); ``` 3. **Maintain correct parameter order** in equality assertions with (expected, actual) to generate meaningful error messages: ```cpp // Correct: ASSERT_EQ(expected_reference, actual_result) ASSERT_EQ(4, img.channels()); EXPECT_EQ(6, lines[0][0]); ``` 4. **Use specialized assertions** for common comparisons instead of custom loops: ```cpp // Use instead of manual matrix comparison loops EXPECT_MAT_NEAR(src_mat, dst_mat, 0); // or EXPECT_PRED_FORMAT2(cvtest::MatComparator(0, 0), src_mat, dst_mat); ``` Well-written assertions make tests more reliable, easier to debug, and help identify the exact cause of failures. --- ## Use semantically accurate names Variable, method, and class names should accurately reflect their actual behavior and purpose. Misleading or vague names create confusion and make code harder to understand and maintain. Key principles: - Names should describe what the code element actually does, not what it was originally intended to do - Avoid generic names when specific ones are more appropriate - Choose names that eliminate ambiguity about the element's role or state Examples of improvements: ```python # Bad: misleading name params_reader.put_nonblocking("LiveParameters", msg_dat) # writes but called "reader" # Good: accurate name params_writer.put_nonblocking("LiveParameters", msg_dat) # Bad: vague name def switchEsimProfile(iccid: str): # Good: clear action def setEsimProfile(iccid: str): # Bad: ambiguous state "ENABLED": 1 # could mean active or just available # Good: specific meaning "LKAS_AVAILABLE": 1 # Bad: generic name def daemon_alive(cam): # Good: descriptive purpose def camera_thread(cam): ``` When reviewing names, ask: "Does this name accurately describe what this code element actually does or represents?" If there's any ambiguity or mismatch between the name and behavior, suggest a more precise alternative. --- ## Choose efficient implementations When implementing algorithms, prioritize both correctness and performance by selecting appropriate data structures, optimizing memory usage, and leveraging language features. ### Comparison functions Implement proper three-way comparisons that handle equality cases correctly: ```cpp // INCORRECT: Returns only -1 or 1, missing 0 for equality inline int WeightedDeltaCompare(const void* const a, const void* const b) { return (reinterpret_cast(a)->delta - reinterpret_cast(b)->delta) <= 0 ? 1 : -1; } // CORRECT: Returns -1, 0, or 1 for proper ordering inline int WeightedDeltaCompare(const void* const a, const void* const b) { float delta_a = reinterpret_cast(a)->delta; float delta_b = reinterpret_cast(b)->delta; if (delta_a < delta_b) return -1; if (delta_a > delta_b) return 1; return 0; } ``` ### Memory optimization Defer memory allocation until needed to avoid unnecessary resource consumption: ```cpp // INEFFICIENT: Creates vector regardless of whether it will be used std::vector uint16_data; if (GetDataType() != QNN_DATATYPE_SFIXED_POINT_16) { return; } // EFFICIENT: Only creates vector when it will be used if (GetDataType() != QNN_DATATYPE_SFIXED_POINT_16) { return; } std::vector uint16_data; ``` ### Vector initialization Use std::iota for sequential initialization instead of manual loops: ```cpp // INEFFICIENT: Manual population of sequential values std::vector values; for (int i = 0; i < 32768; i++) { values.push_back(i); } // EFFICIENT: Use std::iota for sequential initialization std::vector values(32768); std::iota(values.begin(), values.end(), TypeParam(0)); ``` ### Resource management Use std::move when transferring collections to optimize performance: ```cpp // INEFFICIENT: Copying elements one by one for (const auto& op_wrapper : op_wrappers) { graph_op_wrappers.emplace_back(op_wrapper); } // EFFICIENT: Moving entire collection at once std::move(op_wrappers.begin(), op_wrappers.end(), std::back_inserter(graph_op_wrappers)); ``` ### Mathematical correctness Ensure mathematical algorithms handle edge cases and are implemented according to their proper definitions: ```cpp // INCORRECT: Wrong implementation of floormod // floormod(x,y) = (x/y) - floor(x/y) // CORRECT: Proper implementation with additional multiplication // floormod(x,y) = ((x/y) - floor(x/y))*y ``` ### Numeric stability Be vigilant about integer overflow, especially in calculations involving ranges or large numbers: ```cpp // VULNERABLE to overflow when limit-start is large auto size_auto = Eigen::numext::ceil(Eigen::numext::abs((limit - start) / delta)); // SAFER approach to avoid overflow auto size_auto = Eigen::numext::ceil( Eigen::numext::abs((limit / delta) - (start / delta))); ``` --- ## Choose appropriate pointer types Select the right pointer type based on ownership semantics to prevent null reference issues and memory leaks. Follow these guidelines: 1. Use smart pointers (`shared_ptr`, `unique_ptr`) when ownership transfer is needed 2. Use `weak_ptr` for non-owning references to shared objects to avoid cyclic dependencies 3. Raw pointers are appropriate only when the object's lifetime is guaranteed to exceed the pointer's usage Be explicit about object lifecycle by properly defining or deleting special member functions in classes that manage resources. ```cpp // GOOD: Clear ownership with smart pointer std::unique_ptr monitor_ = std::make_unique(); // GOOD: Non-owning reference to shared object, avoids cyclic dependency std::weak_ptr processGroup_; // ACCEPTABLE: Raw pointer when lifecycle is contained within parent // HeartbeatMonitor(ProcessGroupNCCL* pg); // Only if pg's lifetime > HeartbeatMonitor // GOOD: Explicitly handle or delete copy semantics to prevent null reference issues struct MPSCachedKernel { MPSCachedKernel(NSObject* object) : _object([object retain]) {} MPSCachedKernel(const MPSCachedKernel&) = delete; // Prevent accidental copies // ... }; ``` --- ## Feature flag convention Establish a consistent pattern for feature flags and dependency management in configuration files: 1. Use `WITH_*` or `OPENCV_ENABLE_*` variables to represent user intentions (features to enable if available) 2. Perform proper detection with `find_package()` and preferably `try_compile()` to validate dependencies 3. Set `HAVE_*` variables based on actual availability check results 4. Always guard feature usage in code with `HAVE_*` checks 5. Prefer target-based dependencies over simple flag checks 6. Make compile definitions PUBLIC when they affect interface headers Example: ```cmake # User intention ocv_option(OPENCV_ENABLE_EGL_INTEROP "Build with EGL interoperability support" ON) # Actual detection (in main CMakeLists.txt) if(OPENCV_ENABLE_EGL_INTEROP) find_package(EGL) if(EGL_FOUND) set(HAVE_EGL_INTEROP ON) endif() endif() # Usage in module CMakeLists.txt if(HAVE_EGL_INTEROP) # Prefer target-based dependencies target_link_libraries(${the_module} PUBLIC ocv.3rdparty.egl) # Make definitions PUBLIC if used in headers target_compile_definitions(${the_module} PUBLIC HAVE_EGL_INTEROP) endif() ``` This convention ensures all dependencies are properly detected during configuration stage, not build stage, preventing build failures due to missing dependencies. It clearly separates user intent from actual availability and promotes modern CMake practices. --- ## Optimize tensor operation chains When working with PyTorch tensors, look for opportunities to optimize operation chains for better performance and memory efficiency. This involves two key strategies: 1. **Use inplace operations when safe**: For non-leaf tensors, inplace operations (+=, *=, etc.) can reduce memory allocation and improve performance. Check if a tensor is a leaf node before deciding: ```python def optimized_add(x: torch.Tensor, value: float) -> torch.Tensor: if x.is_leaf: x = x + value # Create new tensor for leaf nodes else: x += value # Inplace operation for non-leaf nodes return x ``` 2. **Mathematically simplify operation chains**: Look for algebraically equivalent expressions that require fewer operations: ```python # Instead of: x.add(1.0).div(2.0).clamp(0,1).mul(255.).round() # Use: x.add(1.0).clamp(0,2).mul(127.5).round() # This eliminates one operation while maintaining mathematical correctness ``` These optimizations are particularly important in neural network forward/backward passes where tensor operations are performed repeatedly on large data. Always verify mathematical equivalence when simplifying operation chains, and profile performance gains in your specific use case. --- ## Use environment variables Make configuration values configurable through environment variables with sensible defaults instead of hard-coding them. This improves flexibility and testability while maintaining backward compatibility. Use `os.getenv()` with appropriate type conversion and default values: ```python # Good: Configurable with defaults YUV_BUFFER_COUNT = int(os.getenv("YUV_BUFFER_COUNT", "20")) DUAL_CAMERA = bool(int(os.getenv("DUAL", "0"))) CAMERA_ROAD_ID = int(os.getenv("CAMERA_ROAD_ID", "0")) # Bad: Hard-coded values YUV_BUFFER_COUNT = 20 DUAL_CAMERA = False CAMERA_ROAD_ID = 0 ``` For platform-specific behavior, prefer hardware abstraction over hard-coded paths: ```python # Good: Use hardware abstraction USER_AGENT = f"AGNOSSetup-{HARDWARE.get_os_version()}" # Bad: Hard-coded file reading USER_AGENT = f"AGNOSSetup-{open('/VERSION').read().strip()}" ``` This approach allows runtime configuration changes, easier testing with different values, and better separation of configuration from code logic. --- ## Use authoritative data sources When working with network-related data, always read from the most direct and authoritative source available rather than making assumptions or relying on indirect indicators. This ensures accuracy and robustness in network operations. For network connections, query the active connection state directly instead of inferring properties from adapter information. For data format detection, examine file headers or content signatures rather than relying solely on file extensions that may be absent or misleading. Example of preferred approach: ```cpp // Instead of guessing from adapter bool WifiManager::currentNetworkMetered() { // Read from active connection directly return getActiveConnectionMeteredStatus(); } // Instead of relying only on file extensions if (url.find(".bz2") != std::string::npos) { data = decompressBZ2(data, abort); } else { // Also detect from file header like python LogReader if (detectBZ2Header(data)) { data = decompressBZ2(data, abort); } } ``` This approach prevents issues when indirect indicators (like file extensions) are removed or when adapter properties don't accurately reflect the actual network state. --- ## Guard optional dependencies Configuration management requires careful handling of optional dependencies in both build scripts and source code. Always guard code that depends on optional modules or libraries with appropriate feature guards, and check for component existence before using them. In build scripts: ```cmake # Check for optional components before using them FIND_LIBRARY(WEBP_MUX_LIBRARY NAMES webpmux) if(WEBP_MUX_LIBRARY) SET(WEBP_LIBRARIES ${WEBP_LIBRARIES} ${WEBP_MUX_LIBRARY}) endif() ``` In header files: ```cpp // Guard features that depend on optional modules #ifdef HAVE_OPENCV_DNN // DNN-dependent code here #endif ``` For configuration variables, use standardized naming conventions: - `HAVE_` prefix for feature availability (e.g., `HAVE_ZLIB` instead of `ZLIB_FOUND`) - `OPENCV_` prefix for OpenCV-specific settings to avoid conflicts (e.g., `OPENCV_ANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES`) When detecting incompatible dependencies, provide clear messages and fallback options: ```cmake if(HAVE_CXX17 AND OPENEXR_VERSION VERSION_LESS "2.3.0") message(STATUS "OpenEXR(ver ${OPENEXR_VERSION}) doesn't support C++17. Updating OpenEXR 2.3.0+ is required.") # Provide fallback or clear error endif() ``` --- ## Consistent descriptive naming Use clear, descriptive names that follow consistent patterns established in the codebase and broader programming standards. This includes: 1. Choose unambiguous function names that clearly communicate purpose and behavior: ```cpp // Poor: Hard to understand what it does and how it differs from copyTo() void overwriteTo(OutputArray m) const; // Better: Clearer indication of behavior void writeTo(OutputArray m) const; ``` 2. Avoid unnecessary abbreviations when clarity would be improved: ```cpp // Poor: Ambiguous abbreviation CV_WRAP void computeCCM(); // Better: Clear meaning CV_WRAP Mat computeColorCorrectionMatrix(); ``` 3. Use all capital letters with underscores for constants and enums: ```cpp // Poor: Inconsistent capitalization enum ColorCheckerType { COLORCHECKER_Macbeth, COLORCHECKER_Vinyl }; // Better: Consistent all-caps for constants enum ColorCheckerType { COLORCHECKER_MACBETH, COLORCHECKER_VINYL }; ``` 4. Follow established naming patterns for related classes or components: ```cpp // Poor: Inconsistent with existing naming patterns enum DisposalMethod { GRFMT_GIF_Nothing = 0, GRFMT_GIF_PreviousImage = 1 }; // Better: Consistent naming pattern enum GifDisposeMethod { GIF_DISPOSE_NONE = 1, GIF_DISPOSE_RESTORE_PREVIOUS = 3 }; ``` 5. Name setters with 'set' prefix for clarity: ```cpp // Poor: Confusing whether this is getter or setter int paletteSize(int setPaletteSize = 0); // Better: Clear indication this is a setter int setPaletteSize(int size); ``` This approach leads to more maintainable, readable, and self-documenting code while preserving consistency across the codebase. --- ## Optimize container access Choose efficient container types and optimize access patterns in performance-critical code. Avoid operations that cause hidden allocations and minimize overhead when accessing container elements. **Key practices:** 1. **Avoid in-place operations** that cause hidden copies: ```cpp // Bad: causes hidden .clone() call inputMat.convertTo(inputMat, CV_8UC1, 1.0 / 256); // Good: use a separate destination inputMat.convertTo(convertedMat, CV_8UC1, 1.0 / 256); ``` 2. **Use flat arrays instead of nested containers** for better cache locality and reduced overhead: ```cpp // Bad: vector of vectors has high overhead std::vector> hist256(channels, std::vector(256, 0)); // Good: single flat vector std::vector hist256(channels * 256, 0); ``` 3. **Extract raw pointers** from containers for tight loops: ```cpp // Bad: repeatedly accessing vector methods in tight loops for (int i = 0; i < size; i++) { result += hist256[c][i]; } // Good: extract pointer once before loop std::vector hist256vec(256, 0); uint16_t* hist256 = hist256vec.data(); for (int i = 0; i < size; i++) { result += hist256[i]; } ``` 4. **Use stack allocation when possible** instead of dynamic allocation: ```cpp // Bad: unnecessary heap allocation if (condition) { std::vector *dst = new std::vector(size); // use dst delete dst; } // Good: stack allocation with proper scope std::vector dst; if (condition) { dst.resize(size); // use dst } ``` Choose container types based on actual performance measurements rather than assumptions, as the best data structure can vary by platform and usage pattern. --- ## Graceful API evolution When modifying, deprecating, or replacing APIs, ensure a smooth transition experience for developers by following these practices: 1. **Add deprecation warnings** when removing or changing public APIs to alert users: ```python @deprecated( "`isinstance(treespec, LeafSpec)` is deprecated, " "use `isinstance(treespec, TreeSpec)` and `treespec.is_leaf()` instead.", category=FutureWarning, ) class LeafSpec(TreeSpec): # ... ``` 2. **Provide clear migration paths** in deprecation messages and documentation that show exactly how to transition from old APIs to new ones. 3. **Manage public exports** by updating `__all__` lists to remove deprecated items, preventing new code from adopting soon-to-be-removed APIs. 4. **Ensure interoperability** between old and new implementations during transition periods, allowing gradual migration without breaking existing code. 5. **Consider API surface area** when making changes - private APIs may change more freely, while public APIs require more careful transition planning. Following these practices helps maintain trust with developers using your libraries and reduces friction during necessary API evolution. --- ## Optimize for common cases When implementing algorithms, create specialized versions for common cases to improve performance, while maintaining a generic version for completeness. For functions that process data with different channel counts, implement separate optimized code paths for 1-channel and 3-channel data, which represent the majority of image processing workloads. For example, in histogram-based median filtering: ```cpp // Specialized version for 1-channel images if (channels == 1) { uint16_t* hist0 = hist256[0].data(); for (int x = x_start; x != x_end; x += x_step) { // Optimized single-channel histogram update } } // Specialized version for 3-channel images else if (channels == 3) { uint16_t* hist0 = hist256[0].data(); uint16_t* hist1 = hist256[1].data(); uint16_t* hist2 = hist256[2].data(); for (int x = x_start; x != x_end; x += x_step) { // RGB-specific histogram update } } // Generic version for other channel counts else { for (int x = x_start; x != x_end; x += x_step) { // Generic multi-channel implementation } } ``` Structure loops efficiently to avoid redundant calculations. When processing arrays, consider vectorization boundaries and ensure proper handling of edge cases with minimum conditional branches. For iterative algorithms with fixed-size vectors, implement a tail-handling pattern: ```cpp size_t i = 0; for (; i <= len - vl; i += vl) { // Process full vector width } if (i < len) { size_t tail_len = remaining_elements(len - i); // Process remaining elements } ``` This pattern avoids unnecessary modulo operations and extra variables for tracking remainders. When implementing algorithms with specialized branches, ensure that all cases are handled correctly, including those that don't meet optimization criteria. --- ## Document properly with references Always separate code from documentation and use proper referencing techniques. Documentation should be in markdown files when extensive, while code should be in files that are regularly checked for compilation. When documenting APIs: 1. Use `CV_EXPORTS_W` for functions that should be included in Java and Python bindings 2. Reference existing documentation rather than duplicating descriptions 3. Use `@snippet` and `@include` directives to embed code examples in documentation 4. Ensure all parameters are fully documented **Example - Avoid:** ```cpp /** @brief Enum of the possible types of ccm. */ enum CCM_TYPE { CCM_3x3, ///< The CCM with the shape \f$3\times3\f$ performs linear transformation on color values. CCM_4x3, ///< The CCM with the shape \f$4\times3\f$ performs affine transformation. }; // [followed by 200+ lines of in-header documentation] ``` **Example - Prefer:** ```cpp /** @brief Enum of the possible types of ccm. * @see @ref ccm_documentation for detailed explanations */ enum CCM_TYPE { CCM_3x3, ///< The CCM with the shape \f$3\times3\f$ performs linear transformation CCM_4x3, ///< The CCM with the shape \f$4\times3\f$ performs affine transformation }; ``` With detailed documentation in a markdown file referenced by `@ref ccm_documentation` and any code examples included via `@snippet` or `@include` directives. --- ## Use optimized functions When implementing algorithms, prefer using OpenCV's built-in optimized functions over writing custom implementations. OpenCV's library functions are typically vectorized, extensively tested, and optimized for performance across different platforms and hardware architectures. Key examples: 1. Use `inRange()` instead of custom saturation checks (Discussion 7) 2. Use `cv::sum()` for channel operations instead of manually splitting and summing (Discussion 9) 3. Consider converting frequently used operations to vectorized functions that can leverage SIMD instructions (Discussion 10, 17) 4. Use mathematical functions with scalar parameters when available, such as `divide(src, 2, dst)` instead of creating intermediate matrices (Discussion 20) 5. Use OpenCV's metrics functions like `cv::PSNR()` instead of custom implementations (Discussion 42) 6. Prefer `cv::RNG` over standard library random generators for deterministic behavior and testability (Discussion 47) Example - Instead of this: ```cpp Mat saturate(Mat& src, const double& low, const double& up) { Mat dst = Mat::ones(src.size(), CV_8UC1); MatIterator_ it_src = src.begin(), end_src = src.end(); MatIterator_ it_dst = dst.begin(); for (; it_src != end_src; ++it_src, ++it_dst) { for (int i = 0; i < 3; ++i) { if ((*it_src)[i] > up || (*it_src)[i] < low) { *it_dst = 0; break; } } } return dst; } ``` Use this: ```cpp Mat saturate(Mat& src, const double& low, const double& up) { Mat dst; inRange(src, Scalar(low, low, low), Scalar(up, up, up), dst); return dst; } ``` --- ## Structure documentation comprehensively Documentation should provide complete, practical information while maintaining logical organization and information hierarchy. Ensure sections include all necessary details for users to successfully implement or understand the feature, and organize content to flow logically from basic to advanced concepts. When adding new documentation sections: 1. Include complete practical information (not just basic examples) 2. Place sections in logical order based on user journey 3. Group related content together (user-focused vs. developer-focused) For example, when documenting Docker usage: ```shell # Complete example with practical details docker run -it --rm \ -v /path/to/models:/app/models \ -v /path/to/output:/app/output \ -p 8188:8188 \ -e COMFYUI_PORT=8188 \ ghcr.io/comfyanonymous/comfyui:latest-cu124 ``` Rather than just: ```shell # Incomplete - only shows how to pull docker pull ghcr.io/comfyanonymous/comfyui:latest-cu124 ``` Organize sections to follow user progression: Introduction → Getting Started → Features → Advanced Topics → Development/Release Information. --- ## Meaningful semantic naming Choose names that clearly communicate purpose and follow consistent patterns across the codebase: 1. Use generic function names when the functionality is reusable, with parameters for specific values: ```python # Instead of: def check_have_ipp_flag(cmake_file): # Check specifically for HAVE_IPP flag # Prefer: def check_cmake_flag_enabled(cmake_file, flag_name): # Check for any flag ``` 2. When extending functionality that changes a method's signature, create a new method with a descriptive name rather than modifying the existing one: ```python # Instead of changing: corners, ids, rejected = aruco_detector.detectMarkers(img) # To: corners, ids, rejected, extra = aruco_detector.detectMarkers(img) # Create a new method: corners, ids, rejected, extra = aruco_detector.detectMarkersMultiDict(img) ``` 3. Apply naming conventions consistently using established patterns in the codebase rather than creating special cases. If a mechanism exists for handling naming scenarios (like namespace prefixing for functions), use it for similar cases too. --- ## Document configuration version requirements Make build configuration options explicit and document their version dependencies. When introducing configuration parameters that are version-specific, clearly indicate compatibility requirements and provide command-line options to make constraints optional when appropriate. For example, instead of hardcoding checks or settings: ```python # Not recommended: Hardcoded check with no option to disable check_have_ipp_flag(os.path.join(builder.libdest, "CMakeVars.txt")) # Better approach: Make the check configurable if args.strict_dependencies: check_have_ipp_flag(os.path.join(builder.libdest, "CMakeVars.txt")) # When defining version-specific configurations, document requirements # and use proper syntax ABI("3", "arm64-v8a", None, 21, cmake_vars=dict( # Supported in Android NDK r27 and higher, ignored in earlier versions ANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES='ON' )) ``` This approach ensures that configuration options remain flexible while clearly communicating version requirements to developers, preventing unexpected behavior across different environments. --- ## Prevent memory leaks Always ensure proper memory management when using dynamic allocation. Memory leaks are a critical performance issue that can degrade application performance over time and eventually lead to resource exhaustion. Instead of using raw pointers with `new` without corresponding `delete` operations: 1. Prefer smart pointers (std::unique_ptr, std::shared_ptr) to manage object lifetimes automatically 2. Follow RAII (Resource Acquisition Is Initialization) principles 3. If raw pointers must be used, ensure each allocation has a matching deallocation in appropriate cleanup methods Poor example (potential memory leak): ```cpp ShapeDescriptor *descriptor = new ShapeDescriptor(dtype, order, shape); // Missing corresponding delete ``` Better example: ```cpp // Using smart pointer std::unique_ptr descriptor = std::make_unique(dtype, order, shape); // No explicit delete needed, memory will be freed automatically // Or if raw pointer is necessary ShapeDescriptor *descriptor = new ShapeDescriptor(dtype, order, shape); try { // use descriptor // ... delete descriptor; // Clean up when done } catch (...) { delete descriptor; // Clean up on exceptions too throw; } ``` --- ## Enforce least privilege Configure all systems with the minimum permissions required to function. For Kubernetes deployments, use security contexts that prevent privilege escalation and running as root: ```yaml securityContext: runAsNonRoot: true allowPrivilegeEscalation: false runAsUser: 65532 # Use specific non-root UID matching Dockerfile ``` For RBAC permissions, regularly audit and remove unnecessary permissions. Test thoroughly after removing permissions to ensure the application still functions correctly. When introducing new permissions, document their purpose and limit their scope as much as possible. Following this principle reduces attack surface and minimizes potential damage from compromised components. --- ## Maintain code consistency Keep code clean and consistent with established project conventions. This includes: 1. Follow existing formatting style in files: ```cpp // Follow Allman style if file uses it void function() { if (condition) { statement; } } ``` 2. Avoid `using namespace` declarations as they pollute the namespace, even if the header is not included directly. 3. Remove dead/commented-out code or guard it with macros if needed for future use: ```cpp // Instead of leaving commented code blocks // for (int i1 = 0; i1 < STEP_SIZE; ++i1) { // if (ptr + i1 < n1) { // matOut[ptr + i1] = matA[ptr1 + i1] + matB[ptr2 + i1]; // } // } // Use feature macros if code might be needed later #ifdef EXPERIMENTAL_FEATURE for (int i1 = 0; i1 < STEP_SIZE; ++i1) { if (ptr + i1 < n1) { matOut[ptr + i1] = matA[ptr1 + i1] + matB[ptr2 + i1]; } } #endif ``` 4. Prefer C++ templates over complex multi-line macros for better debugging and type safety. 5. Use standard type names rather than shortcuts (e.g., `unsigned char` instead of `uchar`). Consistency in code style significantly improves readability and maintainability while reducing review friction. --- ## Framework synchronization practices When implementing concurrent code, always use the framework's provided synchronization primitives rather than direct language features. This ensures compatibility across all build configurations and platforms: 1. Use OpenCV synchronization mechanisms like `cv::getInitializationMutex()` and `cv::AutoLock` instead of standard C++ constructs like `std::mutex` and `std::lock_guard`: ```cpp // Instead of this: static std::mutex mtx; std::lock_guard lock(mtx); // Use this: cv::AutoLock lock(cv::getInitializationMutex()); ``` 2. Respect system threading settings with `cv::getNumThreads()` rather than hardcoding thread counts: ```cpp // Instead of this: m_parallel_runner = JxlThreadParallelRunnerMake(nullptr, 8); // Hardcoded value // Use this: m_parallel_runner = JxlThreadParallelRunnerMake(nullptr, cv::getNumThreads()); ``` 3. Be aware that thread counts vary by platform (e.g., Android defaults to 2, Linux uses all cores) and that nested parallel operations may be serialized. 4. When using static resources in multithreaded contexts, ensure proper synchronization or consider alternatives like on-demand initialization that avoid static state altogether. These practices ensure your code remains compatible with special configurations like `OPENCV_DISABLE_THREAD_SUPPORT` while maintaining optimal performance across various platforms. --- ## Be specific with exceptions Avoid catching broad exception types like `Exception` and instead catch specific exceptions that you expect and can handle appropriately. When errors occur, they should be explicit rather than failing silently, and should include proper logging or re-raising when necessary. **Key principles:** - Catch specific exception types rather than using broad `except Exception:` clauses - Don't let failures happen silently - add logging or explicit error handling - Re-raise exceptions when you can't handle them properly - Be explicit about what can fail and why **Example of what to avoid:** ```python try: last_parameters_msg.liveParameters.stiffnessFactor = last_parameters_dict['stiffnessFactor'] params_reader.put("LiveParameters", last_parameters_msg.to_bytes()) except Exception: # Too broad, fails silently pass ``` **Better approach:** ```python try: last_parameters_msg.liveParameters.stiffnessFactor = last_parameters_dict['stiffnessFactor'] params_reader.put("LiveParameters", last_parameters_msg.to_bytes()) except (json.JSONDecodeError, KeyError) as e: # Specific exceptions cloudlog.warn(f"Failed to migrate cached params: {e}") ``` This approach makes code more maintainable by clearly documenting what can go wrong and ensuring failures are visible rather than hidden. --- ## Prefer explicit API design When designing APIs, favor simple and explicit interfaces over flexible but complex ones. This reduces cognitive load, improves compile-time checking, and makes the code more maintainable. Key principles: 1. Use concrete types instead of trait bounds when the use cases are limited 2. Split complex return types into separate methods rather than using variant returns 3. Group related parameters together instead of exposing them separately Example - Instead of flexible but costly: ```rust pub fn vocab(mut self, vocab: HashMap) -> Self { // Implementation } ``` Prefer explicit: ```rust pub fn vocab(mut self, vocab: HashMap) -> Self { // Implementation } ``` Or when dealing with multiple return types, instead of: ```rust fn token_to_word(token: usize) -> Option<(usize, usize)> | Option { // Implementation varies based on sequence count } ``` Prefer separate methods: ```rust fn token_to_word(token: usize) -> Option { // Single sequence implementation } fn token_to_word_with_sequence(token: usize) -> Option<(usize, usize)> { // Multi-sequence implementation } ``` This approach makes APIs more predictable, easier to maintain, and reduces potential runtime errors by catching issues at compile-time. --- ## Cleanup before errors Always ensure all resources are properly released before raising errors to prevent resource leaks. This practice is essential for maintaining system stability and avoiding memory leaks in both normal and error conditions. When handling errors, follow this pattern: 1. Set an error flag when an error condition is detected 2. Perform all necessary cleanup operations 3. Only then raise the actual error This approach is particularly important when working with external resources like Python references, locks, file handles, and memory allocations. For example, instead of immediately raising an error: ```cpp // BAD: Error raised before cleanup is performed if (!PyObject_IsInstance(obj, type)) CV_Error(cv::Error::StsBadArg, "Input stream should be derived from io.BufferedIOBase"); // The GIL is never released and 'type' reference is leaked ``` Set a flag, perform cleanup, then raise the error: ```cpp // GOOD: Cleanup performed before raising error bool has_error = false; if (!PyObject_IsInstance(obj, type)) has_error = true; // Cleanup resources regardless of error Py_DECREF(type); PyGILState_Release(gstate); // Raise error after cleanup if (has_error) CV_Error(cv::Error::StsBadArg, "Input stream should be derived from io.BufferedIOBase"); ``` This pattern applies to all error scenarios, whether using exceptions (like CV_Error), assertions (CV_Assert), or returning error codes. By ensuring resources are released before propagating errors, you create more robust code that can handle failure scenarios gracefully. --- ## Build dependency synchronization When adding new imports to code files, always synchronize by updating the corresponding dependencies in BUILD files. Different build environments enforce dependency rules with varying strictness, so proper configuration is essential even if local builds succeed. This helps prevent errors like: ``` ERROR: Strict deps violations: //tensorflow/python/client:device_lib In tensorflow/python/client/device_lib.py, no direct deps found for imports: line 21: from tensorflow.python.platform import tf_logging as logging: Module "tensorflow.python.platform" not provided by a direct dep ``` When adding a new import like `from tensorflow.python.platform import tf_logging as logging`, ensure you also update the appropriate BUILD file to include this dependency, even if your local environment doesn't immediately flag the missing dependency. --- ## Use proper types Maintain code clarity by using appropriate type declarations and parameter passing conventions: 1. **Prefer explicit types over `auto` when the type is known and simple**: ```cpp // Instead of: auto device_ordinal = 0; // Prefer: int device_ordinal = 0; ``` 2. **Use prefix form (`++i`) instead of postfix (`i++`) in loops** for better performance with non-primitive types: ```cpp // Instead of: for (int i = 0; i < perm.NumElements(); i++) // Prefer: for (int i = 0; i < perm.NumElements(); ++i) ``` 3. **Mark variables as `const` when they're not modified**: ```cpp // Instead of: std::vector input_data = CastVector({1, 2, 3, 4, 5, 6}); // Prefer: const std::vector input_data = CastVector({1, 2, 3, 4, 5, 6}); ``` 4. **Pass parameters appropriately**: - Pass lightweight objects like span by value: `void foo(absl::Span dims)` - Pass `const&` for larger objects: `void foo(const std::vector& vec)` - Mark function parameters as `const` when they're not modified 5. **Use C++-style casts instead of C-style casts**: ```cpp // Instead of: *itr = bfloat16(data[i]); rescaled_6 = (int64_t)std::round(6.0f / input_qtype.getScale()) + input_qtype.getZeroPoint(); // Prefer: *itr = static_cast(data[i]); rescaled_6 = static_cast(std::round(6.0f / input_qtype.getScale())) + input_qtype.getZeroPoint(); ``` 6. **Put variables ahead of values being compared to**: ```cpp // Instead of: if (0 > crop_window_vec(2) || 0 > crop_window_vec(3)) // Prefer: if (crop_window_vec(2) < 0 || crop_window_vec(3) < 0) ``` --- ## optimize data structure selection Choose data structures and algorithms based on their computational complexity and access patterns rather than convenience. Consider performance implications when selecting between alternatives. Key principles: 1. **Match data structure to access patterns**: Use `np.array` instead of Python lists when performing mathematical operations, as numpy can optimize operations internally without type conversion overhead. 2. **Choose algorithms based on constraints**: Select streaming algorithms when memory usage matters more than speed, and batch algorithms when speed is critical and memory is available. 3. **Avoid expensive operations in hot paths**: Replace costly operations like `inspect.getmodule()` with simpler alternatives such as direct I/O operations or cached lookups. 4. **Make implementations algorithm-agnostic**: Design interfaces that work with different underlying implementations (e.g., `queue.clear()` vs creating new queue instances). Example from the codebase: ```python # Before: Python list requiring conversion self.posenet_stds = [POSENET_STD_INITIAL_VALUE] * (POSENET_STD_HIST_HALF * 2) old_mean = np.mean(self.posenet_stds[:POSENET_STD_HIST_HALF]) # Converts list to array internally # After: Direct numpy array for better performance self.posenet_stds = np.array([POSENET_STD_INITIAL_VALUE] * (POSENET_STD_HIST_HALF * 2)) old_mean = np.mean(self.posenet_stds[:POSENET_STD_HIST_HALF]) # No conversion needed ``` When choosing between algorithmic approaches, document the trade-offs. For instance, `zstd.decompress()` is faster for files with size headers, while streaming decompression handles variable-size data but with slight performance cost. Choose based on your data characteristics and constraints. --- ## Thread-safe resource cleanup When implementing resource cleanup in concurrent applications, avoid using deprecated finalizers and instead use PhantomReference-based cleanup mechanisms that ensure thread safety. Key considerations: 1. Use PhantomReference with a ReferenceQueue to detect when objects are ready for cleanup 2. Maintain appropriate data structures (e.g., doubly-linked lists) to track references and support efficient removal 3. Implement a dedicated daemon thread to process the cleanup queue 4. Ensure the cleaner object outlives the resources it manages Example implementation: ```java public final class SafeResourceCleaner { private final ReferenceQueue queue = new ReferenceQueue<>(); private final PhantomCleanable phantomCleanableList = new PhantomCleanable(); // Create a single cleaner per application/library component public static SafeResourceCleaner create() { SafeResourceCleaner cleaner = new SafeResourceCleaner(); cleaner.startCleanerThread(); return cleaner; } public Cleanable register(Object resource, Runnable cleanupAction) { return new PhantomCleanable( Objects.requireNonNull(resource), Objects.requireNonNull(cleanupAction) ); } private void startCleanerThread() { Thread thread = new Thread(() -> { while (!isShutdown()) { try { // Use reasonable timeout to allow thread termination if needed Cleanable ref = (Cleanable) queue.remove(60 * 1000L); if (ref != null) { ref.clean(); } } catch (Throwable e) { // Handle exceptions gracefully, never let them terminate the cleaner thread } } }, "ResourceCleaner-Thread"); thread.setDaemon(true); // Don't prevent JVM shutdown thread.start(); } } ``` This approach is particularly important for concurrent applications where thread safety must be maintained during resource cleanup, and it provides a more reliable alternative to the deprecated finalize() method. --- ## Consistent variable naming Use ALL_CAPS for constants and environment variables in shell scripts, and reference these variables consistently throughout the script with proper quoting. This improves code readability and prevents errors when handling paths with spaces. Example: ```bash # Correct OUTPUT_FILE=tf_env.txt PYTHON_BIN_PATH="$(which python || which python3 || die "Cannot find Python binary")" # Then reference consistently "${PYTHON_BIN_PATH}" -c 'import sys; print(sys.version_info[:])' # Incorrect python_bin_path=$(which python || which python3 || die "Cannot find Python binary") python -c 'import sys; print(sys.version_info[:])' # Inconsistent reference ``` Using a consistent naming convention makes scripts more maintainable and helps other developers understand which values are constants. Double-quoting variables (like `"${PYTHON_BIN_PATH}"`) ensures that paths with spaces are handled correctly. --- ## Verify platform compatibility first When writing networking code that interacts with platform-specific features, always check for the existence of platform-specific functions or resources before attempting to use them. This prevents runtime errors when your code runs in different environments (Windows, Linux, macOS, containers) that might have different capabilities or implementations. For example, when detecting network environment properties: ```python import platform # Good practice - check if function exists before using def get_network_platform_info(): info = {} # Define platform functions that might provide network-related information platform_checks = [ ("network_os", "system"), ("container_environment", "freedesktop_os_release"), ("virtual_machine", "mac_ver") ] # Only use functions that exist on the current platform for label, function_name in platform_checks: if hasattr(platform, function_name): function = getattr(platform, function_name) info[label] = function() else: info[label] = "N/A" return info ``` This approach ensures your networking code gracefully handles different platforms rather than failing with attribute errors when a particular function isn't available. --- ## Intentional Test Coverage All unit tests should be (1) intentionally designed for coverage, (2) non-redundant, and (3) maintainable. Apply these rules: 1) Enforce correctness with invariants - When the system under test has known relationships, assert them directly and return a clear error code on violation. - Example (CPU topology): ```cpp int cpucount = ncnn::get_cpu_count(); int bigcpucount = ncnn::get_big_cpu_count(); int littlecpucount = ncnn::get_little_cpu_count(); if (bigcpucount + littlecpucount != cpucount || bigcpucount > cpucount || !(littlecpucount < cpucount)) return -1; ``` 2) Cover critical tensor ranks/shapes, not just “typical” ones - If a layer/operator supports multiple ranks or expects specific dimensionalities, add targeted tests for the missing ranks (e.g., 1D and 4D when relevant). - Make rank coverage a checklist item when adding/adjusting operator tests. 3) Reuse shared test helpers for layer/model execution - Prefer existing generic helpers (e.g., a `test_layer<>`-style utility) instead of duplicating manual layer creation, parameter loading, pipeline creation, and forward logic. - Only write bespoke setup when the helper cannot express the needed test scenario. 4) Remove duplicated or near-identical test cases - Deduplicate test vectors/case lists. If new cases are added, ensure they add distinct coverage (different shapes/parameters/edge conditions), rather than repeating the same configuration. - If duplication is discovered, consolidate into a parameterized list or a shared test case generator. Result: tests become smaller, faster to review, easier to maintain, and less likely to miss regressions due to missing shape variants or redundant cases. --- ## optimize CI resource usage Design CI/CD workflows to minimize unnecessary resource consumption and provide faster feedback. Avoid triggering builds when changes don't impact the build output, use appropriate event triggers, and implement clean artifact management strategies. Key practices: - Use conditional triggers or path filters to avoid building when changes don't affect the build (e.g., documentation-only changes shouldn't trigger Docker builds) - Choose appropriate workflow triggers - prefer `release: types: [published]` for production deployments rather than building on every branch push - Implement clean tagging strategies to avoid registry pollution - use `type=edge,branch=master` instead of `type=ref,event=branch` and avoid unnecessary tags like `type=sha` or `type=ref,event=pr` - Reduce timeout values for faster failure detection (e.g., reduce wait times from 10 minutes to 30 seconds) - Consider matrix complexity - support only variants with known demand rather than "every platform that a compiler supports just because they can" Example of efficient workflow triggers: ```yaml on: release: types: [published] # Only build on actual releases push: branches: [master] paths-ignore: ['docs/**', '*.md'] # Skip builds for doc changes ``` This approach reduces CI costs, speeds up feedback loops, and prevents resource waste while maintaining necessary build coverage. --- ## Meaningful consistent names Choose names that are both semantically precise and follow consistent conventions. Names should accurately reflect behavior and purpose while adhering to established patterns in the codebase. **Function naming:** - Boolean functions should clearly indicate their predicate meaning ```cpp // Poor: Function returns true for zero values too bool IsPositive(const HloInstruction* hlo) // Better: Name accurately describes behavior bool IsNonNegative(const HloInstruction* hlo) ``` - If a function extracts or returns more than a boolean, the name should reflect this ```cpp // Poor: Name suggests it only returns true/false bool IsShapedUint8Type(OpBuilder& builder, const Type type, Type& rescaled_type) // Better: Name indicates it extracts information bool ExtractUint8TypeInfo(OpBuilder& builder, const ShapedType type, Type& rescaled_type) ``` **Variable naming:** - Use descriptive names that indicate purpose rather than implementation ```cpp // Poor: Technical implementation detail auto a0_pad_const_op = rewriter.create(); // Better: Role-based description auto padding_const_op = rewriter.create(); ``` - Prefer full words over abbreviations for clarity ```cpp // Poor: Abbreviated form bool merge_h_to_d_stream = true; // Better: Fully descriptive bool merge_host_to_device_stream = true; ``` **Consistency:** - Follow established casing conventions: - Use camelCase for helper functions: `thisIsTheFunctionName()` - Use snake_case for variables: `empty_lines` not `emptyLines` - Be consistent with compound terms: "LiteRt" not "LiteRT" - Maintain consistent naming styles within related components to improve API cohesion These naming practices improve readability, maintainability, and reduce bugs caused by misunderstandings about code behavior. --- ## Validate before dereference Always check that pointers, optional values, and results of type casts are valid before dereferencing or using them. This prevents null pointer exceptions, undefined behavior, and potential crashes in production. For pointers obtained from operations or external sources: ```cpp // Before accessing a pointer's members if (value.getDefiningOp() != nullptr) { // Now safe to use value.getDefiningOp()->getResult(0) } ``` For optional values, verify presence before access: ```cpp auto shared_library_dir = FindDispatchOption(options, num_options, kDispatchOptionSharedLibraryDir); if (shared_library_dir.HasValue()) { shared_library_dir_opt.emplace(std::any_cast(shared_library_dir.Value())); } ``` For dynamic casts, check success before using the result: ```cpp auto input_type = input_value.getType().dyn_cast(); if (!input_type) { op->emitOpError("Input type not ranked tensor"); return nullptr; } ``` When designing APIs, preserve nullability expectations to maintain compatibility: ```cpp // Check parameters that might be null rather than requiring non-null if (run_metadata != nullptr) { // Only use run_metadata when it's provided } ``` --- ## leverage native configuration features When configuring applications in containerized environments, prefer using the application's built-in configuration mechanisms over extensive external configuration like multiple volume mounts or environment variable overrides. This approach reduces complexity, improves maintainability, and leverages the application's intended configuration patterns. For example, instead of mounting multiple individual directories: ```yaml volumes: - "./models:/app/models" - "./input:/app/input" - "./temp:/app/output/temp" - "./output:/app/output" - "./user:/app/user" - "./custom_venv:/app/custom_venv" - "./custom_nodes:/app/custom_nodes" ``` Use the application's native configuration support with a single base directory and let the application manage its internal structure: ```yaml volumes: - "./data:/home/comfyui/data" command: ["--base-directory", "/home/comfyui/data"] ``` This pattern applies broadly - look for CLI arguments, configuration files, or environment variables that allow applications to self-organize their directory structure and file locations rather than imposing external mounting schemes. Additionally, avoid mixing conflicting configuration options (like `image` + `build` in Docker Compose) that can lead to unexpected behavior. --- ## Container security best practices Implement comprehensive security measures in containerized applications to prevent privilege escalation, injection attacks, and unauthorized access. This includes proper user configuration, variable quoting, and secure process handling. Key security practices: 1. **Use secure user IDs**: Use UID/GID 999 (standard for official images) instead of 1000 to reduce container escape risks 2. **Quote shell variables**: Always quote variables in shell commands to prevent injection attacks 3. **Implement proper file permissions**: Use restrictive umask (0077) to limit file access to owner only 4. **Handle process switching securely**: Use `setpriv` for secure user switching and `exec` for proper signal handling Example of secure variable quoting: ```dockerfile # Vulnerable - unquoted variables CMD python -u main.py --listen ${COMFYUI_ADDRESS} --port ${COMFYUI_PORT} # Secure - quoted variables CMD python -u main.py --listen "${COMFYUI_ADDRESS}" --port "${COMFYUI_PORT}" ``` Example of secure user configuration: ```dockerfile # Use standard secure UID/GID ARG USER_UID=999 ARG USER_GID=999 # Create system user with restricted permissions RUN adduser --system --home /home/user --uid ${USER_UID} --group user ``` These practices significantly reduce attack surface and prevent common container security vulnerabilities. --- ## Platform-specific socket configuration When configuring TCP socket options, always check the platform and apply appropriate settings for each operating system. Different platforms support different socket options and may require different approaches for connection management. Use proper platform detection with `sys.platform` to conditionally apply socket options. For example, `TCP_USER_TIMEOUT` is Linux-specific, while `TCP_KEEPALIVE` is used on Darwin (macOS). Always provide fallbacks or alternative approaches for unsupported platforms. Example implementation: ```python if sys.platform == 'linux': sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_USER_TIMEOUT, 16000 if onroad else 0) sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, 7 if onroad else 30) elif sys.platform == 'darwin': sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPALIVE, 7 if onroad else 30) ``` This approach ensures reliable network connections across different deployment environments and prevents runtime errors from unsupported socket operations. Consider the specific networking requirements of your application (timeouts, keepalive intervals) and how they should vary by platform and operational state. --- ## pin external action versions Always pin external GitHub Actions to specific commit hashes rather than using tags or branch names, and prefer built-in runner capabilities when available. This improves security by preventing supply chain attacks and ensures reproducible builds. Unpinned actions create security vulnerabilities and can break workflows when external maintainers update their actions. Additionally, using built-in runner features reduces external dependencies and improves performance. Example of proper pinning: ```yaml # Bad - using tag - uses: stefanzweifel/git-auto-commit-action@v5 # Good - pinned to commit hash - uses: stefanzweifel/git-auto-commit-action@8621497c8c39c72f3e2a999a13b1c01d91af5b75 # Even better - use built-in capabilities when possible # Instead of actions/setup-python@v5.3.0, use: runs-on: ubuntu-24.04 # comes with python 3.12 pre-installed ``` Always research if the runner already provides the needed functionality before adding external dependencies. --- ## Benchmark performance changes Always include performance benchmarks when making changes that could impact execution speed, CPU usage, or resource consumption. This prevents performance regressions and validates optimization claims. For any performance-related pull request, provide before/after measurements using appropriate benchmarking tools. Include specific metrics like execution time, CPU usage, or throughput improvements. Example benchmark format: ```python # Before optimization old_parse_structs(): 7.900648624985479 seconds # After optimization new_parse_structs(): 5.590290749911219 seconds ``` This practice is essential because performance regressions can be subtle but significant - like the locationd process that "uses 2-3x more CPU than the previous" version, or CAN parsing changes that initially appeared "twice as slow." Without benchmarks, these issues may go unnoticed until they impact system performance in production. Benchmarks should be run on representative hardware and workloads, and results should demonstrate meaningful improvements or at minimum show no regression in critical performance metrics. --- ## Parameterize hardcoded API values When designing APIs or interfaces, avoid hardcoding string literals, configuration values, or identifiers that could be made configurable through parameters. This makes the API more flexible, reusable, and maintainable by allowing callers to specify their own values rather than being locked into fixed behavior. Hardcoded values in APIs create tight coupling and reduce reusability. Instead, expose these values as parameters in your interface design, allowing different use cases to be supported without code changes. Example of the problem: ```cpp // Bad: hardcoded "thumbnail" string pm.reset(new PubMaster({encoder_info.publish_name, "thumbnail"})); ``` Better approach: ```cpp // Good: parameterize the thumbnail name through EncoderInfo pm.reset(new PubMaster({encoder_info.publish_name, encoder_info.thumbnail_name})); ``` This principle applies to API endpoints, configuration keys, default values, and any identifier that might need to vary across different contexts or use cases. By parameterizing these values, you create more flexible interfaces that can adapt to different requirements without requiring code modifications. --- ## Centralize configuration settings Place configuration settings in centralized, appropriate locations rather than duplicating them across multiple files. This improves maintainability by ensuring changes only need to be made in one place. For build configurations: - Use the root `.bazelrc` file for settings that apply across multiple configurations - Place platform-specific configurations in dedicated locations (e.g., platform targets in `tools/toolchains`) - Use existing configuration hierarchies like `release_base` or `release_cpu_linux` for settings that apply to groups of configurations For code configurations: - Consolidate common configuration options into shared variables/lists - Avoid duplicating the same settings in multiple places Example: ```python # Bad: Duplicating settings in multiple environment-specific files # ci/official/envs/continuous_linux_x86_cpu_py310 # ci/official/envs/continuous_linux_arm64_cpu_py310 # ... # Good: Single definition in .bazelrc # .bazelrc build:release_base --define=some_feature=enabled build:release_cpu_linux --config=release_base --some_other_setting=value ``` Similarly, for code: ```python # Bad: Duplicating settings across multiple configuration sets _DNNL_RUNTIME_THREADPOOL = { "#cmakedefine01 DNNL_WITH_SYCL": "#define DNNL_WITH_SYCL 0", "#cmakedefine01 DNNL_WITH_LEVEL_ZERO": "#define DNNL_WITH_LEVEL_ZERO 0", } _DNNL_RUNTIME_OMP = { "#cmakedefine01 DNNL_WITH_SYCL": "#define DNNL_WITH_SYCL 0", "#cmakedefine01 DNNL_WITH_LEVEL_ZERO": "#define DNNL_WITH_LEVEL_ZERO 0", } # Good: Define common settings once _CMAKE_COMMON_LIST = { "#cmakedefine01 DNNL_WITH_SYCL": "#define DNNL_WITH_SYCL 0", "#cmakedefine01 DNNL_WITH_LEVEL_ZERO": "#define DNNL_WITH_LEVEL_ZERO 0", } _DNNL_RUNTIME_THREADPOOL = dict(_CMAKE_COMMON_LIST) _DNNL_RUNTIME_OMP = dict(_CMAKE_COMMON_LIST) ``` This approach reduces maintenance burden and helps prevent inconsistencies that arise when settings are updated in some places but not others. --- ## Test algorithmic behavior When testing algorithms, verify their actual functionality rather than just checking for proper instantiation or property modification. Ensure your tests capture the core behaviors of the algorithm under various parameters. For deterministic algorithms: - Test with different input parameters and verify the expected output - Include edge cases that might affect algorithm behavior For non-deterministic algorithms: - Focus on testing invariant properties rather than exact outputs - Identify the stable parts of the output that should always be consistent Example: ```python # Insufficient test - only checks properties def test_fixed_length_weak(): pretok = FixedLength(length=5) assert pretok.length == 5 pretok.length = 10 assert pretok.length == 10 # Better test - verifies actual algorithm behavior def test_fixed_length_complete(): test_string = "This is a test string for tokenization" # Test with length=5 pretok = FixedLength(length=5) output_5 = pretok.pre_tokenize(test_string) assert len(output_5[0]) == 5 # First chunk should be 5 chars assert "".join([t for t, _ in output_5]) == test_string # Original text preserved # Test with length=10 pretok.length = 10 output_10 = pretok.pre_tokenize(test_string) assert len(output_10[0]) == 10 # First chunk should be 10 chars assert len(output_10) < len(output_5) # Fewer chunks with larger length ``` For algorithms with inherent variability (like probabilistic models), focus on testing stable properties rather than specific outputs that might change between runs. --- ## Prefer asynchronous operations Use asynchronous patterns to prevent blocking operations from degrading system performance, especially in UI contexts and real-time systems. Prefer higher-level async abstractions like std::future over manual thread management when possible, as they provide automatic thread management, better exception handling, and simpler code maintenance. For UI operations, ensure any potentially blocking calls (even those taking 0.1s) are made asynchronous to maintain smooth frame rates. For system operations that may block due to external factors (like network timeouts or hardware buffer states), isolate them in separate threads to prevent cascading delays. Example from brightness control: ```cpp // Preferred: Using std::future for automatic thread management if (!brightness_future.valid() || brightness_future.wait_for(std::chrono::seconds(0)) == std::future_status::ready) { brightness_future = std::async(std::launch::async, Hardware::set_brightness, brightness); } // Avoid: Manual thread management requiring explicit cleanup and exception handling if (!brightness_thread || !brightness_thread->joinable()) { brightness_thread = std::make_unique(wrapper_function, brightness); } ``` When operations must remain in separate threads due to blocking behavior (such as hardware buffer management), document the reasoning clearly and implement appropriate error handling for synchronization failures. --- ## Environment variable consistency Ensure consistent formatting and proper usage of environment variables in Dockerfiles. Remove unnecessary quotes from ENV declarations and choose between ARG and ENV based on their intended scope - use ARG for build-time configuration that may change between builds, and ENV for runtime configuration that containers need during execution. Key guidelines: - Remove unnecessary quotes from ENV values unless the value contains spaces or special characters - Use ARG for build-time parameters that configure the build process - Use ENV when the variable needs to be available during container runtime or in RUN commands - Maintain consistency in formatting across all environment variable declarations Example: ```dockerfile # Good - consistent formatting, appropriate usage ARG PYTHON_VERSION=3.11 ENV PIP_CACHE_DIR=/cache/pip ENV VIRTUAL_ENV=/app/venv ENV TRANSFORMERS_CACHE=/app/.cache/transformers # Avoid - unnecessary quotes and inconsistent formatting ENV PIP_CACHE_DIR="/cache/pip" ENV VIRTUAL_ENV=/app/venv ENV TRANSFORMERS_CACHE="/app/.cache/transformers" ``` This approach improves readability, reduces confusion about when quotes are necessary, and ensures proper separation between build-time and runtime configuration. --- ## Check nulls directly Check objects directly for null/empty state instead of using separate tracking variables. Always perform null checks early in your functions, before entering resource-intensive blocks or operations that assume non-null values. **Don't do this:** ```cpp // Using a separate boolean flag to track object state std::shared_ptr qbar_sr; bool net_loaded_ = false; // Redundant tracking variable void someFunction() { if (net_loaded_) { // Indirect check through tracking variable qbar_sr->performOperation(); } } ``` **Do this instead:** ```cpp // Check the object directly std::shared_ptr qbar_sr; void someFunction() { if (qbar_sr) { // Direct check of the object itself qbar_sr->performOperation(); } } ``` And always check for null parameters at the beginning of functions: ```cpp void processData(const char* name) { // Check nulls early, before any processing or resource allocation if (name == NULL) { handleError("NULL name parameter"); return; } // Now it's safe to use the parameter processName(name); } ``` This approach improves code readability, reduces state tracking errors, and prevents null dereference bugs by ensuring validation happens before any operations that assume non-null values. --- ## Header hygiene rules Keep headers “composition-safe” and minimal. Apply these rules: - **Do not define non-inline function implementations in headers.** Put the implementation in a `.cpp` file to avoid multiple-definition/linker problems. - **Avoid leaking preprocessor macros from headers.** If a constant/behavior is needed, prefer `constexpr`, `enum`, or an internal-scoped construct rather than a global `#define`. - **Use correct include discipline.** Remove duplicated includes and avoid unnecessary headers. Ensure all declarations are protected by appropriate header/platform guards. Example (bad → good): ```cpp // bad: in header // foo.h int gettimeofday_impl(); // ... int gettimeofday_impl() { return 0; } // implementation in header // good: in header // foo.h int gettimeofday_impl(); // foo.cpp int gettimeofday_impl() { return 0; } ``` Checklist for changes to `.h` files: - Are there any **function bodies** (non-`inline`) in the header? - Are there any **global `#define`** entries? - Are there **duplicate/unneeded includes**? - Are declarations properly **guarded** (header guard / platform guard)? --- ## Standardize configuration approaches When documenting or implementing configuration procedures, prioritize standard, unified approaches over custom or platform-specific solutions. This applies to setup scripts, environment activation, and configuration management. For setup procedures, favor consolidated scripts that work across platforms: ```bash # Preferred: unified approach tools/op.sh setup # Avoid: platform-specific manual steps # Ubuntu 24.04: # tools/ubuntu_setup.sh # macOS: # tools/mac_setup.sh ``` For environment management, stick to familiar standard practices rather than introducing custom commands: ```bash # Preferred: standard Python environment activation source .env/bin/activate # Avoid: custom commands that require special knowledge openpilot_shell ``` This approach reduces cognitive load for developers, leverages existing knowledge, and maintains consistency across different environments. Only introduce custom configuration methods when standard approaches are insufficient for the specific use case. --- ## Prevent null vulnerabilities Use container classes and smart pointers instead of manual memory allocation to prevent null pointer dereferences and memory leaks. **Instead of raw memory allocation:** ```cpp // Problematic: Potential memory leak if exceptions occur uint32_t* buffer = new uint32_t[size]; // ... operations that might throw delete[] buffer; // May never be reached ``` **Prefer container classes:** ```cpp // Better: Automatic cleanup even with exceptions std::vector buffer(size); // or cv::AutoBuffer buffer(size); // May use stack space for small allocations ``` **For custom resource types, use smart pointers with appropriate deleters:** ```cpp // Problematic: Manual resource management WebPAnimDecoder* decoder = WebPAnimDecoderNew(&webp_data, &dec_options); // ... operations WebPAnimDecoderDelete(decoder); // May be forgotten or skipped due to early returns // Better: Automatic cleanup with custom deleter struct UniquePtrDeleter { void operator()(WebPAnimDecoder* decoder) const { WebPAnimDecoderDelete(decoder); } }; std::unique_ptr decoder(WebPAnimDecoderNew(&webp_data, &dec_options)); ``` **When null is invalid, use references instead of pointers:** ```cpp // Problematic: Needs null check uint32_t read_chunk(CHUNK* pChunk); // Better: NULL is not possible uint32_t read_chunk(CHUNK& pChunk); ``` Proper memory management not only prevents memory leaks but also eliminates many null pointer scenarios, making your code more robust and easier to maintain. --- ## eliminate unnecessary code Remove redundant code constructs and prefer concise, direct patterns that improve readability and maintainability. This includes eliminating unnecessary widget/layout creation, using ternary operators for simple conditionals, direct initialization patterns, and simplifying complex calculations with named constants. Examples of improvements: - Instead of creating wrapper widgets unnecessarily: `routes_type_selector_->addTab(preserved_route_list_ = new RouteListWidget, tr("&Preserved"));` - Use ternary operators for simple conditionals: `return routes_type_selector_->currentIndex() == 0 ? route_list_ : preserved_route_list_;` - Direct layout attachment: `auto layout = new QVBoxLayout(widget)` instead of separate `setLayout()` calls - Replace complex calculations with named constants: `const QColor ENGAGED_COLOR = QColor::fromRgbF(0.1, 0.945, 0.26);` instead of inline math - Eliminate unnecessary variable assignments and prefer direct initialization where possible This approach reduces code bloat, makes intent clearer, and improves maintainability by removing opportunities for errors in redundant code paths. --- ## Optimize git network operations When performing git operations that involve network communication, use proper syntax and efficient strategies to minimize data transfer and ensure correct remote branch handling. For remote branch fetching, always specify both remote and local branch names to avoid ambiguity and ensure the branch is properly tracked locally: ```bash # Preferred: explicit remote:local syntax git fetch origin $1:$1 # Avoid: ambiguous fetch that may not create local branch git fetch origin $1 ``` For repository cloning, consider using shallow clones with `--depth=1` to reduce initial network transfer, especially for testing or CI environments where full history isn't needed: ```bash # Efficient for testing/CI git clone --depth=1 https://github.com/user/repo.git # Note: shallow clones can be unshallowed later if needed git fetch --unshallow ``` This approach reduces network bandwidth usage while maintaining the ability to expand the repository scope when necessary. Always consider the trade-offs between initial clone speed and future git operation capabilities when choosing clone strategies. --- ## Configuration parameter documentation Ensure all configuration parameters have explicit default values and are thoroughly documented. When using argparse with `action='store_true'`, always pair it with `default=False`. Document parameter purposes, valid values, and default behaviors in README files. For dependency management, separate conflicting requirements into different files to avoid version incompatibilities. Example: ```python # Good: Explicit default value parser.add_argument('--use_modelscope', action='store_true', default=False, help='Whether to use ModelScope; if False, HuggingFace is used') parser.add_argument('--generate_length', type=int, default=2048, help='Number of tokens to generate (default: 2048)') ``` In README documentation: ```markdown Parameters: - `--use_modelscope`: Whether to use ModelScope; if False, HuggingFace is used; default is False - `--generate_length`: Number of tokens to generate; default is 2048 ``` For dependencies, use separate requirement files: ``` requirements/perf_transformer.txt # For transformer-specific dependencies requirements/perf_vllm.txt # For vLLM-specific dependencies ``` --- ## Verify AI library compatibility When specifying AI/ML library dependencies, ensure version compatibility between related packages and verify that prebuilt binaries are available for the target environment. Many AI libraries like auto_gptq, autoawq, and flash_attn are compiled against specific versions of PyTorch and CUDA, and version mismatches can force compilation from source or cause runtime failures. Before finalizing requirements, check: - Library compatibility matrices (e.g., auto_gptq 0.7.1 requires torch 2.2.1, not 2.3.1) - Availability of prebuilt wheels for your CUDA version - Whether dependencies require CUDA compilers if building from source Consider separating incompatible libraries into different requirements files when necessary. Example of problematic dependencies: ``` torch==2.3.1 auto_gptq==0.7.1 # Compiled against torch 2.2.1, will cause issues ``` Better approach: ``` # requirements-gptq.txt torch==2.2.1 auto_gptq==0.7.1 # requirements-awq.txt torch==2.4.1 autoawq==0.2.6 ``` --- ## AI library version compatibility When documenting AI/ML model deployment and inference procedures, always test and specify compatible library versions to prevent runtime failures. Version incompatibilities in AI libraries can cause critical errors like inference failures, probability tensor issues, or model output corruption. Key practices: - Test all documented version combinations before publication - Specify exact working versions when known incompatibilities exist - Document alternative versions when primary versions fail - Include version-specific notes for critical functionality Example from model deployment documentation: ```bash # Working configuration auto_gptq==0.6.0+cu1210 # Note: >=0.7.0 causes RuntimeError with probability tensors # vLLM version notes vLLM==0.6.2 # Recommended for Qwen2.5 7B/14B/32B with 128k context vLLM==0.6.3 # May cause output issues: !!!!!!!!!!!!!!!!!!!!!!! ``` This prevents users from encountering runtime errors like "probability tensor contains either `inf`, `nan` or element < 0" or model output corruption, ensuring reliable AI model deployment and inference. --- ## Eliminate redundant code Keep code clean by removing all forms of redundancy that affect readability and maintainability. This includes: 1. Avoid duplicate macro/constant definitions that could cause conflicts or confusion ```c++ // BAD - duplicated macro definition #define ARRAY_IS_VIEW 33554432 #define ARRAY_IS_VIEW 33554432 // Duplicate! // GOOD - defined once #define ARRAY_IS_VIEW 33554432 ``` 2. Remove debug print statements from production code unless they're part of error handling ```c++ // BAD - debug statement in production code registerUse({&res}, {this}); sd_printf("After before exec\n",0); // Debug print in production code // GOOD - only in error paths or removed entirely registerUse({&res}, {this}); // No unnecessary print statements ``` 3. Keep configuration files clean without redundant/duplicate content (such as repeated license headers) Each form of redundancy impacts code readability and increases maintenance burden. When reviewing code, make sure information is stated once and only once where appropriate. --- ## Optimize workflow triggers Configure CI workflows with targeted triggers and path filters to balance thoroughness with efficiency. Run critical build jobs on every commit for affected components, while avoiding unnecessary builds when changes don't impact certain components. For example, use path filters to only run specific workflows when relevant files change: ```yaml name: Node Build on: push: paths: - 'bindings/node/**' - 'src/**' paths-ignore: - '*.md' - 'docs/**' pull_request: paths: - 'bindings/node/**' - 'src/**' jobs: build: # Build configuration here ``` Keep your CI components updated to their latest stable versions: ```yaml - name: Install Python uses: actions/setup-python@v5 # Use latest stable version ``` Consider workflow organization - separate workflows by component or purpose, but look for opportunities to consolidate setup steps and reuse configuration across similar jobs. --- ## Optimize cache key design Design cache keys to avoid performance pitfalls and ensure reliable cache behavior. Cache keys should be lightweight, hashable, and deterministic to prevent unnecessary cache misses and memory bloat. Key principles: 1. **Avoid large objects in cache keys** - Large values like images or models should not be part of the cache key as they bloat memory and slow down key comparison 2. **Ensure hashability** - Unhashable objects (like MODEL instances) in cache keys will cause nodes to always be considered 'dirty' and re-evaluated 3. **Use references over values** - Forward links to previous nodes rather than actual values when possible to keep keys lightweight 4. **Cache expensive key computations** - Store intermediate results of expensive signature calculations to avoid repeated work within execution cycles Example of problematic cache key design: ```python # BAD: Large image data becomes part of cache key cache_key = (node_id, large_image_tensor, other_inputs) # BAD: Unhashable model object causes cache misses cache_key = (node_id, model_instance, inputs) ``` Example of optimized cache key design: ```python # GOOD: Use link references instead of actual values if is_link(input_data): cache_key = (node_id, ("ANCESTOR", ancestor_index, socket)) else: cache_key = (node_id, input_data) # Only for small, hashable data # GOOD: Cache expensive signature computations if node_id not in self.immediate_node_signature: self.immediate_node_signature[node_id] = self.compute_signature(node_id) ``` This approach ensures cache keys remain efficient while maintaining cache correctness, preventing both performance degradation and incorrect cache behavior. --- ## Structure for navigation Documentation should be structured to optimize user navigation and information discovery. When organizing documentation elements: 1. Group related information into logical categories to help users find relevant content faster 2. Maintain consistent formatting and width across similar elements for better readability 3. Consider user scanning patterns - users often skim content, so key information should be easily visible 4. Use alphabetical sorting within groups to create predictable navigation patterns For example, when creating documentation indexes or navigation elements: ```yaml # Good organization example documentation_links: # Community resources (general info) - name: Documentation url: https://docs.example.org/ about: Official Documentation - name: Community Support url: https://community.example.org/ about: Get help from the community # Component-specific resources (alphabetically sorted) - name: API Reference url: https://api.example.org/ about: Please refer to the API documentation - name: Installation Guide url: https://install.example.org/ about: Follow the installation steps ``` This organization style makes navigation intuitive and ensures users can quickly find the information they need, rather than getting lost in poorly structured documentation. --- ## Centralize configuration values Store all configuration values in dedicated configuration files rather than hardcoding them throughout the application. This makes the codebase more maintainable and reduces the need for code changes when configurations change. Key practices: - Use environment files to store configuration values - Move hardcoded patterns, URLs, and paths to configuration constants - Design configuration with future extensibility in mind - Use environment variables for feature toggles and configurable behavior **Example - Before:** ```typescript constructor(private translate: TranslateService) { const currentLanguage = this.translate.getBrowserLang(); const lang = currentLanguage.match(/en|fr/) ? currentLanguage : 'en'; } constructor(iconRegistry: MatIconRegistry, sanitizer: DomSanitizer) { iconRegistry.addSvgIcon('jupyterlab', sanitizer.bypassSecurityTrustResourceUrl('static/assets/jupyterlab-wordmark.svg')); } ``` **Example - After:** ```typescript // In environment.ts export const environment = { supportedLanguages: ['en', 'fr'], defaultLanguage: 'en', assetPaths: { jupyterlab: 'static/assets/jupyterlab-wordmark.svg', } }; // In component constructor(private translate: TranslateService) { const currentLanguage = this.translate.getBrowserLang(); const lang = environment.supportedLanguages.includes(currentLanguage) ? currentLanguage : environment.defaultLanguage; } constructor(iconRegistry: MatIconRegistry, sanitizer: DomSanitizer) { iconRegistry.addSvgIcon( 'jupyterlab', sanitizer.bypassSecurityTrustResourceUrl(environment.assetPaths.jupyterlab) ); } ``` This approach makes it easier to add new languages or assets without modifying component code, and keeps configuration organized in central locations. --- ## Structured documentation with examples Create comprehensive documentation with clear structure and practical examples. Documentation should include: 1. **Standard documentation files** like README.md, CHANGELOG.md, and CONTRIBUTING.md, even if they primarily link to external resources. Search engines index these standard files, improving project discoverability. 2. **Well-organized content** with clear headings, tables for related information, and consistent formatting. For complex projects, organize information hierarchically: ```markdown # Component Name ## About Brief description of the component's purpose. ## Table of Components | Component | Source Repository | |-----------|-------------------| | Component A | [`org/repo-a`](https://github.com/org/repo-a) | | Component B | [`org/repo-b`](https://github.com/org/repo-b) | ## Usage Examples ``` 3. **Usage examples** demonstrating common tasks. For instance, when documenting test procedures: ```markdown **Run all tests** `make run` **Run component-specific tests** `make run-kfp` # Run Kubeflow Pipelines tests `make run-katib` # Run Katib tests ``` 4. **Active voice** rather than passive voice to improve clarity and directness. 5. **Links to stable versions** rather than development branches to prevent users from accidentally using unstable code. Following these practices makes documentation more useful, accessible, and maintainable while improving the overall user experience. --- ## maintain CI/CD parity Ensure CI/CD pipeline tools run with the same configuration, flags, and behavior as developers use locally. This prevents masking errors in CI/CD that developers would encounter in their local environment and maintains consistency in the development workflow. When configuring linting, testing, or other quality tools in CI/CD scripts, avoid adding flags or modifications that change the tool's behavior compared to local usage. For example, avoid adding `--quiet` flags or different file selection criteria that could hide issues developers need to see. Example of what to avoid: ```bash # This masks errors that developers see locally run "ruff" ruff check $PYTHON_FILES --quiet ``` Instead, ensure CI/CD runs the same commands developers would run: ```bash # This matches what developers run locally: "ruff check ." run "ruff" ruff check $PYTHON_FILES ``` This principle applies to all CI/CD tools including linters, formatters, test runners, and build tools. The goal is to eliminate surprises where something passes in CI/CD but fails locally, or vice versa. --- ## Centralize configuration constants Store configuration constants, defaults, and environment variable mappings in dedicated configuration files rather than duplicating them across the codebase. This provides a single source of truth, improves maintainability, and reduces errors from inconsistent values. For environment variables with defaults: ```python # In a central config.py file: METRICS = bool(os.environ.get("METRICS", False)) BACKEND_MODE = os.environ.get("BACKEND_MODE", BackendMode.PRODUCTION.value) # In application code: from config import METRICS, BACKEND_MODE ``` For registry references, version constants, and other configuration mappings: ```python # In config.py AWS_REGISTRIES = { "jupyter": "public.ecr.aws/j1r0q0g6/jupyter-web-app", "volumes": "public.ecr.aws/j1r0q0g6/volumes-web-app", # Add more as needed } # In application code: from config import AWS_REGISTRIES registry = AWS_REGISTRIES["jupyter"] ``` When system-wide defaults are available (like in configmaps), prefer those over hardcoded values to ensure consistency across components. --- ## Environment variable management Manage environment variables in Docker configurations with appropriate scope, placement, and documentation: 1. **Set environment variables with appropriate scope**: - Use variables only where needed, not globally - Set temporary variables like `DEBIAN_FRONTEND` only within the commands that need them: ```dockerfile # Do this: RUN apt-get update \ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ package1 package2 # Not this: ENV DEBIAN_FRONTEND=noninteractive RUN apt-get update && apt-get install -y package1 package2 ``` 2. **Place variables logically**: - Group related variables under descriptive comments - Place variables near their related commands - Use ARG instead of ENV for build-time values, especially versions: ```dockerfile # version details ARG LIBFABRIC_VERSION="1.20.0" ARG PYTORCH_VERSION="2.2.2" ``` 3. **Document variables properly**: - Add comments explaining non-obvious configurations - Include links to relevant documentation when appropriate - Document compatibility requirements: ```dockerfile # Gaudi does not currently support Python 3.11, so we downgrade to 3.10 # https://docs.habana.ai/en/latest/Support_Matrix/Support_Matrix.html ``` 4. **Clean up unnecessary variables**: - Remove obsolete or unused environment variables - Consider using dedicated configuration files under /etc/ instead of environment variables when appropriate --- ## Standardize network tools When performing network operations in build scripts or containers, prefer `curl` over `wget` for HTTP requests to standardize dependencies and improve portability. Use the specific flags `-fsSL` for silent operation with proper error handling, and explicitly specify output destinations. Additionally, ensure network services support both IPv4 and IPv6 addressing by using dual-stack binding configurations rather than binding only to 0.0.0.0 (IPv4). Example replacing wget with curl: ```bash # Instead of: wget -q -O- https://example.com/file.tar.gz | tar xz # Use: curl -fsSL https://example.com/file.tar.gz | tar xz ``` Example of dual-stack binding in gunicorn: ```bash # Instead of: gunicorn -w 3 --bind 0.0.0.0:5000 app:app # Use: gunicorn -w 3 --bind 0.0.0.0:5000 --bind [::]:5000 app:app ``` --- ## Document with precision Write informative, consistent, and precise code comments throughout your codebase. When documenting code: 1. **Be specific with references** - When referencing external repositories or sources, link to specific versions and files, not just directories. Use precise language to describe the relationship between your code and external sources. ``` # AVOID: # Content below is extracted from scripts/Dockerfiles here: # https://github.com/HabanaAI/Setup_and_Install/tree/main/dockerfiles/base # BETTER: # Content below is based on: # https://github.com/HabanaAI/Setup_and_Install/blob/1.17.0/dockerfiles/base/Dockerfile.ubuntu22.04 ``` 2. **Add explanatory comments** - Include brief descriptions for significant code blocks, especially when installing components or defining important configurations. ``` # AVOID: RUN python3 -m pip install habana_media_loader=="${VERSION}"."${REVISION}" # BETTER: # Install Habana media loader library for PyTorch integration RUN python3 -m pip install habana_media_loader=="${VERSION}"."${REVISION}" ``` 3. **Maintain consistent styles** - Use consistent comment headers and styles across similar files to improve readability and maintainability. ``` # AVOID mixing styles: # version details # and elsewhere: # args - software versions # BETTER: Use consistent headers: # args - software versions ``` Well-documented code improves comprehension, facilitates maintenance, and enhances collaboration among team members. --- ## Clean up your code Maintain clean, professional code by removing development artifacts and improving readability: 1. **Remove debug code before committing**: - Delete all debugging print statements - Remove commented-out code blocks - If keeping temporarily disabled code is necessary, add a clear TODO comment ```java // Bad: System.out.println("Functrace on: " + funcTrace); // Bad: // ptrDataBuffer.closeBuffer(); // if(pointer != null && !pointer.isNull()) // pointer.close(); // If really necessary: // TODO: Re-enable this after fixing JIRA-1234 // ptrDataBuffer.closeBuffer(); ``` 2. **Replace magic numbers with named constants**: - Extract hard-coded numeric literals into meaningful constants - Place constants at the class level for reuse and clarity ```java // Bad: if (edgeCount - lastEdgeCount > 10000) { // ... } // Good: private static final int EDGE_COUNT_REPORT_THRESHOLD = 10000; if (edgeCount - lastEdgeCount > EDGE_COUNT_REPORT_THRESHOLD) { // ... } ``` 3. **Format precondition checks properly**: - Use string formatting instead of concatenation to avoid unnecessary object creation - Include the actual values in the error message for easier debugging ```java // Bad: Preconditions.checkArgument(data >= 0, "Values for " + paramName + " must be >= 0, got: " + data); // Good: Preconditions.checkArgument(data >= 0, "Values for %s must be >= 0, got %s", paramName, data); ``` 4. **Add private constructors to utility classes**: - Prevent instantiation of utility classes with private constructors ```java // Good: public class ValidationUtils { private ValidationUtils() { // Private constructor to prevent instantiation } // Static utility methods... } ``` --- ## Cache expensive operations Identify operations that are expensive and called frequently, then optimize them by caching results, moving to appropriate lifecycle events, or replacing with faster alternatives. Expensive operations like parameter reads, system calls, or complex computations should not be repeated unnecessarily in hot code paths. For example, instead of calling expensive parameter reads on every update: ```cpp // Avoid: Called on every update (expensive) bool AnnotatedCameraWidget::isDMAlwaysOn() const { Params params; return params.getBool("AlwaysOnDM"); // params.get() is expensive } ``` Move the expensive operation to initialization or appropriate lifecycle events: ```cpp // Better: Update once when widget becomes visible void AnnotatedCameraWidget::showEvent(QShowEvent *event) { Params params; dm_always_on = params.getBool("AlwaysOnDM"); // Cache the result } ``` Similarly, replace slow system operations with faster alternatives when available. A 16ms operation replaced with a 0.5ms equivalent can significantly improve responsiveness in frequently called code paths. --- ## Complete docstring structure Function documentation should follow a consistent structure that includes all necessary components to be complete and usable. Each docstring should: 1. Start with a one-line summary that concisely describes the function's purpose 2. Include an "Args" section that documents all parameters 3. Format "Returns" section as noun phrases (not full sentences) 4. Document exceptions when relevant Example of proper docstring structure: ```python def is_platform_supported(precision, gpu_id=0): """Determines if the current NVIDIA GPU platform supports the requested precision. Required Compute Capabilities: - FP16 = 5.3 || 6.0 || 6.2 || 7.0+ - INT8 = 6.1 || 7.0 || 7.2+ Args: precision: String indicating the desired compute precision. gpu_id: Integer ID of the GPU to check. Defaults to 0. Returns: Boolean indicating whether the platform supports the requested precision. Raises: ValueError: If precision is not a supported value. """ ``` Following this structure ensures documentation is consistent, complete, and meets style guidelines. It helps other developers understand your code more quickly and makes automated documentation generation more effective. --- ## Use consistent error handling Apply standardized error handling patterns across your codebase for improved reliability and debugging. For new code, use the `absl` error types instead of `tsl::errors` and include descriptive error messages with context. Key practices: 1. Use `absl` error types with `absl::StrCat` for error messages 2. Perform validation checks early in functions 3. Use appropriate error handling mechanisms for your function's return type 4. Return `StatusOr` for operations that can fail instead of raw values ```cpp // Instead of: return errors::InvalidArgument("Invalid shape: ", shape.DebugString()); // Use: return absl::InvalidArgumentError( absl::StrCat("Invalid shape: ", shape.DebugString())); // For void functions, use the proper macro: OP_REQUIRES(ctx, input.shape().dim_size(i) != 0, absl::InvalidArgumentError("Invalid input: Dimension cannot be 0.")); // For functions that can fail, return StatusOr: StatusOr GetDeviceNameFromStreamDeviceName(const string& stream_name) { if (!IsValidStreamName(stream_name)) { return absl::InvalidArgumentError("Invalid stream device name"); } return ParsedName; } ``` --- ## Modular model components Design machine learning model code with clear component boundaries and proper separation of concerns. Each component (tokenizer, normalizer, model, etc.) should have a single responsibility with appropriate visibility modifiers. Benefits: - Enables customization for different model architectures - Makes testing individual components easier - Improves maintainability as model complexity grows For example, instead of embedding tokenization logic directly in the model: ```rust // Not recommended: Tokenization functionality embedded in model impl ModelClass { pub fn tokenize_and_process(&self, text: &str) -> Result> { // Logic mixing tokenization and model-specific processing } } // Recommended: Separate components with clear responsibilities pub mod tokenizers { pub(crate) fn bytes_char() -> HashMap { // Tokenization logic isolated } } impl ModelClass { // Higher-level API using the tokenizer component pub fn process(&self, tokens: Vec) -> Result { // Model-specific processing only } } ``` When designing ML libraries, consider which functionality belongs in the core model versus specialized components like normalizers, tokenizers, or trainers. This modularity is especially important for generative AI and NLP systems where preprocessing pipelines can vary significantly between model architectures. --- ## Use optional chaining operators Use optional chaining (`?.`) and nullish coalescing (`??`) operators instead of manual null checks to safely access nested properties and provide fallback values. These operators prevent runtime errors when dealing with potentially null or undefined values and result in cleaner, more readable code. Instead of verbose manual checks: ```javascript if (item.meta && item.meta[key] && item.meta[key].display_node) { app.nodeOutputs[item.meta[key].display_node] = value; } else { app.nodeOutputs[key] = value; } ``` Use optional chaining with nullish coalescing: ```javascript const realKey = item?.meta?.[key]?.display_node ?? key; app.nodeOutputs[realKey] = value; ``` For simple property access, replace potentially unsafe access like `input.widget.name` with `input.widget?.name` to handle cases where the parent object might be null or undefined. This approach reduces boilerplate code while providing robust null safety. --- ## Harden container security When building container images, ensure they're compatible with restricted Kubernetes security contexts. Use numeric UIDs instead of symbolic usernames, and test compatibility with the following security constraints: ```yaml securityContext: runAsNonRoot: true allowPrivilegeEscalation: false capabilities: drop: - ALL ``` This approach prevents privilege escalation attacks and follows the principle of least privilege. For example, in a Dockerfile, prefer `USER 1000` over `USER jovyan` to ensure compatibility with security contexts that enforce non-root execution. This practice enhances security in various Kubernetes environments, including those that don't automatically apply these restrictions. --- ## Tool-specific configuration compatibility When working with configuration files that support multiple tools or package managers, ensure that configuration syntax and constraints accommodate all supported tools while maintaining functionality across the ecosystem. Different tools have specific requirements and limitations that must be understood and accommodated. For example, uv requires lower bounds for dependencies in preview mode ("sounddevice >= 0" instead of "sounddevice"), cannot combine github sources with platform markers in the same declaration, and poetry has limitations on non-existent version specifications. Always verify that configuration changes work across all intended tools and document tool-specific constraints when they influence configuration decisions. For static analysis tools like mypy, align version settings with the project's minimum supported version rather than the latest available version to prevent use of unsupported language features. Example from pyproject.toml: ```toml # uv requires lower bounds in preview mode "sounddevice >= 0", # micd + soundd # uv limitation: github source + markers must be split dependencies = [ "metadrive-simulator; platform_machine != 'aarch64'" ] [tool.uv.sources] metadrive-simulator = { git = "https://github.com/commaai/metadrive.git", branch = "python3.12" } # mypy should target minimum supported Python version [tool.mypy] python_version = "3.11" # keep to minimum supported, not latest ``` --- ## Handle nullable types idiomatically Use Rust's idiomatic patterns when working with Option and Result types to prevent panics and improve code clarity. **Avoid unwrapping** Prefer pattern matching or propagating errors instead of using `.unwrap()` which can cause runtime panics: ```rust // Instead of this: fn __str__(&self) -> PyResult { Ok(format!("{}", self.model.read().unwrap())) } // Prefer this: fn __str__(&self) -> PyResult { self.model.read() .map(|model| format!("{}", model)) .map_err(|e| e.into()) // Convert to PyResult } ``` **Use Option types appropriately** Only use Option when a value can truly be absent. For boolean flags, use bool instead of Option unless "no preference" is truly needed: ```rust // Instead of: pub fn from( vocab: Vec<(String, f64)>, unk_id: Option, byte_fallback: Option, // Unnecessarily complex ) -> Result // Prefer: pub fn from( vocab: Vec<(String, f64)>, unk_id: Option, // Truly optional byte_fallback: bool, // Just a flag ) -> Result ``` **Handle Option values clearly** Use clear patterns for handling optional values, remembering that None means absence, not zero: ```rust // Instead of: match max_merge_length { None | Some(0) => { /* in case 0 was manually entered, treat as None */ } Some(length) => { /* handle length */ } } // Prefer: if let Some(max_token_length) = max_token_length { if new_token.chars().count() > max_token_length { continue; } } ``` **Design for nullable parameters** When creating APIs with optional parameters, consider how values can be both set and unset: ```rust // Option in builder pattern fn with_dropout(mut self, dropout: Option) -> Self { self.dropout = dropout; self } // Or provide explicit methods fn with_dropout(mut self, dropout: f32) -> Self { self.dropout = Some(dropout); self } fn without_dropout(mut self) -> Self { self.dropout = None; self } ``` --- ## Version AI dependencies appropriately When adding or updating dependencies for AI/ML libraries in your project, follow these two key practices: 1. **Set appropriate version constraints** that balance stability with access to improvements. For rapidly evolving AI libraries like HuggingFace Hub, avoid overly restrictive upper bounds that prevent compatible updates, but also avoid excessively permissive constraints that risk breaking changes. ```toml # Too restrictive dependencies = ["huggingface_hub>=0.16.4,<0.17"] # Better approach - allows minor version updates dependencies = ["huggingface_hub>=0.16.4,<0.18"] # Potentially too permissive for rapidly evolving AI libraries dependencies = ["huggingface_hub>=0.16.4,<1.0"] ``` 2. **Make AI-related dependencies optional** when they're not essential for core functionality. This is especially important for dependencies fetched from Git repositories or those with large footprints. ```toml # Better approach with optional flag arrow = { git = "https://github.com/apache/arrow-rs", branch = "master", features = [ "pyarrow", ], optional=True } ``` This approach reduces unnecessary dependencies for users who don't need all ML features and provides flexibility in environments with compatibility constraints. --- ## Validate quantization parameters carefully When implementing quantized operations in ML models, thoroughly validate quantization parameters to ensure correctness and prevent subtle numerical errors. Key validation points: 1. For int16 quantized operators, verify zero points are exactly 0 2. For quantized tensor operations, ensure consistent scale factors between input and output 3. When one tensor is quantized, verify all related tensors use compatible quantization schemes Example: ```cpp // Good: Proper quantization parameter validation if (input->type == kTfLiteInt16) { TF_LITE_ENSURE_EQ(context, input->params.zero_point, 0); TF_LITE_ENSURE_EQ(context, output->params.zero_point, 0); } // For quantized operations, validate scale consistency if (input->type == kTfLiteInt8 || input->type == kTfLiteInt16) { TF_LITE_ENSURE_EQ(context, input->params.scale, output->params.scale); } // Ensure quantization scheme compatibility if (lhs.IsQuantized()) { if (!rhs.IsQuantized() || !output.IsQuantized()) { return absl::FailedPreconditionError( "If one tensor is quantized, all must be quantized"); } } ``` --- ## Optimize loop operations Minimize expensive operations within inner loops to improve performance. Key practices include: 1. Extract loop-invariant calculations outside of loops ```cpp // Bad: Recalculating the same value in every iteration for (size_t j = 0; j < (output.shape().Dim(dimension) * inner_dimensions_size); j++) { // Loop body } // Good: Calculate once before the loop const size_t loop_limit = output.shape().Dim(dimension) * inner_dimensions_size; for (size_t j = 0; j < loop_limit; j++) { // Loop body } ``` 2. Avoid expensive function calls like `Offset()` in inner loops ```cpp // Bad: Using Offset() in inner loop for (int filter_d1 = filter_d1_start; filter_d1 < filter_d1_end; ++filter_d1) { for (int filter_d2 = filter_d2_start; filter_d2 < filter_d2_end; ++filter_d2) { for (int filter_d3 = filter_d3_start; filter_d3 < filter_d3_end; ++filter_d3) { total += input_data[Offset(input_shape, batch, in_d1, in_d2, in_d3, channel)]; } } } // Good: Calculate indices incrementally // Initialize base_offset before the loops for (int filter_d1 = filter_d1_start; filter_d1 < filter_d1_end; ++filter_d1) { int d1_offset = base_offset + stride_d1 * filter_d1; for (int filter_d2 = filter_d2_start; filter_d2 < filter_d2_end; ++filter_d2) { int d2_offset = d1_offset + stride_d2 * filter_d2; for (int filter_d3 = filter_d3_start; filter_d3 < filter_d3_end; ++filter_d3) { int index = d2_offset + stride_d3 * filter_d3; total += input_data[index]; } } } ``` 3. Use stack-based containers for small data structures: ```cpp // Bad: Using std::vector for small arrays std::vector a1_transpose_dims; // Good: Using small vector optimization llvm::SmallVector a1_transpose_dims; // Or absl::InlinedVector lhs_index; ``` These optimizations can significantly improve performance in computation-intensive applications by reducing memory allocation overhead and unnecessary calculations. --- ## Separate test data Large test data should be separated from test logic to improve readability and maintainability. Move test data into separate files or define as constants at the top of test files. This makes the test bodies clearer and easier to understand. For example, instead of: ```cpp TYPED_TEST(NonQuantizedIntDotGeneralTest, IntTestTypesTensorsWork2) { using StorageT = typename TypeParam::StorageT; const Shape shape_lhs({7, 3, 4}); const Shape shape_rhs({7, 4}); // ... Vector lhs_data_int{ 0, 1, 4, 1, -2, -3, 0, 0, 6, -1, 0, 0, 1, 0, -2, 0, 1, 3, 4, -6, 2, 4, 4, 0, 0, -2, -1, 1, -2, -3, 0, 2, -3, 0, 0, -2, 4, -7, 2, 2, 0, 4, 2, 0, -6, 1, 1, 2, -2, -2, 0, -1, -4, -1, 0, -1, 1, 3, 1, 1, -4, 0, 0, 1, -1, 0, 4, -2, 0, 5, 0, -1, 0, 2, 1, 2, -1, 1, -3, -2, -6, -3, -1, -3}; // ... test logic } ``` Use: ```cpp // At file scope or in a separate header constexpr int64_t kLhsDataInt[] = { 0, 1, 4, 1, -2, -3, 0, 0, 6, -1, 0, 0, 1, 0, -2, 0, 1, 3, 4, -6, 2, 4, 4, 0, 0, -2, -1, 1, -2, -3, 0, 2, -3, 0, 0, -2, 4, -7, 2, 2, 0, 4, 2, 0, -6, 1, 1, 2, -2, -2, 0, -1, -4, -1, 0, -1, 1, 3, 1, 1, -4, 0, 0, 1, -1, 0, 4, -2, 0, 5, 0, -1, 0, 2, 1, 2, -1, 1, -3, -2, -6, -3, -1, -3 }; TYPED_TEST(NonQuantizedIntDotGeneralTest, IntTestTypesTensorsWork2) { using StorageT = typename TypeParam::StorageT; const Shape shape_lhs({7, 3, 4}); const Shape shape_rhs({7, 4}); // ... Vector lhs_data_int(std::begin(kLhsDataInt), std::end(kLhsDataInt)); // ... test logic } ``` Additionally, create separate, focused test cases for different data types or edge cases rather than handling them all in one test with conditional logic. This makes tests easier to maintain and provides clearer failure diagnostics. --- ## Smart configuration defaults Prefer smart configuration defaults that auto-detect the environment instead of requiring explicit configuration flags. When possible, implement automatic detection of the runtime context and provide sensible defaults while still allowing explicit overrides. For example, instead of requiring a boolean flag to control behavior: ```python def __init__( self, tokenizer: Tokenizer, default_to_notebook: bool = False, # ... ) ``` Consider auto-detecting the environment: ```python def __init__( self, tokenizer: Tokenizer, # No default_to_notebook parameter needed # ... ): # Auto-detect if running in a notebook environment use_notebook = _is_in_notebook_environment() # ... ``` Similarly, when changing configuration parameters for backward compatibility, translate legacy boolean parameters to more descriptive string options: ```python # Instead of directly using boolean parameter prepend_scheme = "always" if add_prefix_space else "never" ``` This approach reduces configuration burden on users, provides more intuitive defaults, and makes the API more user-friendly while maintaining compatibility with existing code. --- ## Tensor-aware control flow When working with TensorFlow tensors, avoid using Python comparison operators (`<`, `>=`, `==`) or conditional checks that expect Boolean scalars. Python operators evaluate eagerly and won't work correctly with tensors that represent deferred computations. Instead: 1. Use TensorFlow's conditional operations like `tf.cond` 2. Use comparison functions from `check_ops` module such as `assert_less` 3. Use TensorFlow's mathematical operations for comparisons **Incorrect:** ```python def random_uniform(shape, minval=0, maxval=None, dtype=dtypes.float32): if minval >= maxval: # Will fail if these are tensors raise ValueError("minval must be less than maxval") ``` **Correct:** ```python def random_uniform(shape, minval=0, maxval=None, dtype=dtypes.float32): # Use check_ops for tensor-compatible validation minval = ops.convert_to_tensor(minval, dtype=dtype) maxval = ops.convert_to_tensor(maxval, dtype=dtype) check_ops.assert_less(minval, maxval, message="minval must be less than maxval") ``` This pattern is essential for building TensorFlow graphs that will execute correctly in both eager and graph execution modes, ensuring your AI models behave as expected regardless of execution environment. --- ## Parameterize ci/cd scripts Avoid duplicating CI/CD scripts by leveraging configuration files and parameterization instead of creating multiple similar scripts for different platforms or build scenarios. Use platform-specific configuration options in shared config files (like .bazelrc) or make scripts accept parameters for variant behaviors. For example, instead of having separate build scripts for different compilers: ```bash # Bad: Multiple nearly-identical scripts build_tf_windows.sh # For MSVC build_tf_windows_clang.sh # For Clang # Good: Single script with parameters build_tf_windows.sh --compiler=clang # Or use configuration files bazel build --config=win_clang ``` Similarly, for build parameters like job counts, prefer configurable variables with defaults instead of hard-coding: ```bash # Bad: Hard-coded value cmake --build . --verbose -j $(nproc) # Good: Configurable with default : ${BUILD_NUM_JOBS:=$(nproc)} # Default to nproc if not set cmake --build . --verbose -j ${BUILD_NUM_JOBS} ``` This approach improves maintainability, reduces errors from out-of-sync scripts, and provides flexibility for different build environments and debugging scenarios. --- ## Format lines and comments Ensure all code follows formatting guidelines for readability and consistency. Keep lines under 80 characters, splitting longer lines appropriately across multiple lines when needed. All comments should be written as complete sentences with proper capitalization and ending punctuation. For example, instead of: ```python # autoparallel optimizer - automatically parallelizes graphs by splitting along the batch dimension ``` Write it as: ```python # Autoparallel optimizer - Automatically parallelizes graphs by splitting along # the batch dimension. ``` For longer parameter descriptions in documentation, follow established patterns: ```python - min_graph_nodes: The minimum number of nodes in a graph to optimizer. For smaller graphs, optimization is skipped. - auto_parallel: Automatically parallelizes graphs by splitting along the batch dimension. ``` This improves readability and helps maintain a professional and consistent codebase. --- ## Framework migration instructions When documenting AI framework migrations (like TensorFlow/Keras version changes), provide complete instructions covering both installation and code modifications. Include: 1. Specific package installation commands with version constraints 2. Required import statement changes with before/after examples 3. Environment variable configurations if applicable 4. Edge cases and compatibility considerations Example for Keras 2 to 3 migration: ```python # Installation # pip install tf-keras~=2.16 # Import changes - Before: import tensorflow.keras as keras # or import keras # Import changes - After: import tf_keras as keras # OR to continue using Keras 2 import os os.environ["TF_USE_LEGACY_KERAS"] = "1" # then use original imports ``` This practice ensures AI developers can smoothly transition between framework versions without disrupting their workflows or introducing subtle bugs. --- ## Handle dynamic shapes When implementing tensor-based algorithms, avoid assumptions about fixed tensor shapes by not relying on direct shape attributes (`.shape`, `.ndim`), which may return `None` in graph mode. Instead, use TensorFlow operations like `tf.shape()` and `tf.rank()` which work in both eager and graph execution modes. For validation, use TensorFlow's conditional operations rather than Python conditionals. For example, replace: ```python # Problematic code - may fail in graph mode mat1_shape = mat1.shape dense_rows = mat1_shape[-2] # This might fail if shape is not known if dense_shape[-2] != dense_rows: # Python conditional won't work with tensors raise ValueError("Shapes don't match") ``` With: ```python # Robust code that works in both eager and graph modes mat1_shape = array_ops.shape(mat1) dense_rows = mat1_shape[-2] condition = math_ops.equal(dense_shape[-2], dense_rows) gen_logging_ops._assert(condition, ["Shapes don't match"], name="Assert") ``` This approach ensures algorithms work reliably regardless of whether shapes are statically known at graph construction time or only determined during execution. --- ## Be explicit in references When writing documentation, always be specific and explicit when referring to files, tools, configurations, or other elements. Vague references create confusion and require readers to make assumptions or search for additional context. Provide complete information by: 1. Specifying exact versions and names of tools mentioned Example: Use "Bazel 0.4.5" instead of just "0.4.5" in a table cell 2. Clearly stating file locations when referencing them Example: Write "env files in the envs/ folder" instead of just "env files" 3. Using descriptive headers that accurately reflect content Example: Use "Build tools" instead of "Bazel/Cmake" when the table shows various build tools This practice ensures documentation is immediately clear to all readers, regardless of their familiarity with the codebase, and reduces the need for clarifying questions. --- ## Informative error messages Error messages should be informative, actionable, and concise to help users quickly understand and fix issues. Follow these guidelines: 1. Include specific details in error messages: - Parameter names and values causing the error - Valid ranges or expected types - Actual values that violated constraints 2. Use modern f-strings for better readability: ```python # Avoid raise ValueError('Invalid axis: {} not in range {}-{}'.format(axis, min_val, max_val)) # Prefer raise ValueError(f"Argument `axis` = {axis} not in range [{min_val}, {max_val})") ``` 3. Keep messages focused and concise: ```python # Too verbose raise ValueError(f'Python found at {python_bin_path} is not version 3. Please update to the latest version to continue with installation.') # Better raise ValueError(f'Python from {python_bin_path} is not version 3.') ``` 4. For validation errors, include both the expected and actual values: ```python # Vague raise ValueError("Type annotation does not match input_signature") # Better raise ValueError(f"Type annotation for argument '{arg}' expected {annotation_dtype} but input_signature specified {input_signature_dtype}") ``` Well-crafted error messages reduce debugging time and improve the overall developer experience when using your code. --- ## Return results not panics Libraries should never panic as this can crash applications using the library. Always return a `Result` type rather than using functions or methods that can panic (`panic!()`, `unwrap()`, `expect()`, `assert!()`) in public APIs and internal logic. This allows consumers of your library to properly handle error conditions. For example, instead of: ```rust // BAD: This will panic if the string doesn't match any scheme impl From<&str> for PrependScheme { fn from(s: &str) -> Self { match s.to_lowercase().as_str() { "first" => PrependScheme::First, "never" => PrependScheme::Never, "always" => PrependScheme::Always, _ => panic!("Invalid value for PrependScheme: {}", s), } } } ``` Prefer: ```rust // GOOD: Returns Result so the caller can handle the error impl TryFrom<&str> for PrependScheme { type Error = String; fn try_from(s: &str) -> Result { match s.to_lowercase().as_str() { "first" => Ok(PrependScheme::First), "never" => Ok(PrependScheme::Never), "always" => Ok(PrependScheme::Always), _ => Err(format!("Invalid value for PrependScheme: {}", s)), } } } ``` Similarly, instead of using `.unwrap()` or `.expect()` on `Option`s or `Result`s, propagate errors up the call stack. For public APIs that are expected to succeed under normal circumstances, validate inputs and return informative errors rather than using assertions. When handling regex matches or other operations that theoretically shouldn't fail but might in practice, return appropriate error types rather than assuming success with `.expect()`. This approach makes your library more robust and provides a better experience for users. --- ## Minimize memory allocations Avoid unnecessary memory allocations to improve performance. Each allocation has both CPU and memory overhead that can accumulate significantly, especially in hot code paths. Follow these practices: 1. Avoid intermediate collections - prefer direct processing over collect-then-process patterns: ```rust // Inefficient: Creates a temporary collection let collected = items.map(process).collect::>(); let result = collected.iter().sum(); // Better: Process directly without temporary collection let result = items.map(process).reduce(|a, b| a + b).unwrap_or_default(); ``` 2. Don't allocate in getter methods - return references or copy small values instead: ```rust // Avoid: Returning newly allocated vectors pub fn get_added_tokens(&self) -> Vec { self.added_vocabulary.get_added_tokens() } // Better: Return a reference to existing data pub fn get_added_tokens(&self) -> &[String] { self.added_vocabulary.tokens() } ``` 3. Use references/slices for parameter passing to avoid copies: ```rust // Avoid: Taking ownership of a vector that requires allocation fn process(data: Vec) { /* ... */ } // Better: Accept a slice reference fn process(data: &[u8]) { /* ... */ } ``` 4. Consider extending existing structures rather than creating and combining new ones: ```rust // Instead of creating multiple encodings and merging them later, // extend a single encoding incrementally let mut encoding = Encoding::default(); for item in items { let tokens = tokenize(item); encoding.extend(tokens); } ``` Performance optimizations often involve trading readability for speed - make these tradeoffs intentionally and document when necessary. --- ## Choose semantically clear identifiers Select parameter and method names that accurately describe their purpose and behavior, avoiding ambiguous terms that can lead to confusion. Consider these guidelines: 1. Use descriptive names that reflect the actual behavior: ```rust // AVOID: Parameter name doesn't clearly indicate truncation behavior pub fn truncate(&mut self, max_len: usize, stride: usize, left: bool) { // ... } // BETTER: Use an enum with meaningful names pub fn truncate(&mut self, max_len: usize, stride: usize, direction: TruncationDirection) { // ... } ``` 2. Follow language-specific naming conventions: - In Python interfaces, use lowercase for enum values (`"first"` instead of `"First"`) - In Rust, avoid leading underscores for public functions (`from_string` not `_from_string`) 3. Choose names that prevent confusion between related but different concepts: ```rust // AVOID: Similar method names with different behaviors fn add_tokens(&mut self) { /* ... */ } fn num_added_tokens(&self) { /* ... */ } // BETTER: Clear distinction in naming fn add_tokens(&mut self) { /* ... */ } fn num_special_tokens_to_add(&self) { /* ... */ } ``` When choosing identifiers, always ask: "Would another developer immediately understand what this name represents without looking at its implementation?" --- ## Go export naming conventions In Go, the first letter of an identifier (function, variable, struct field, etc.) determines its visibility outside the package: 1. **Uppercase first letter**: The identifier is exported and accessible from other packages 2. **Lowercase first letter**: The identifier is non-exported and only accessible within its package Always follow these rules: - Use uppercase for functions intended as public API: ```go // Exported - can be called from other packages func DisableCullingAnnotationIsSet(meta metav1.ObjectMeta) bool { // implementation } ``` - Use lowercase for functions meant for internal use only: ```go // Non-exported - only callable within the same package func exists(slice []string, val string) bool { for _, item := range slice { if item == val { return true } } return false } ``` - Name functions to accurately reflect their purpose and return type. Boolean functions should use predicate naming (is*, has*, can*). - For struct fields, use uppercase to allow external access and lowercase to restrict access: ```go type MetricsExporter struct { Component string // Exported - accessible metricsPort int // Non-exported - internal only } ``` - Use consistent error variable names, typically `err` rather than custom names like `kfErr`, `generateErr`, etc. This convention is a critical part of Go's visibility system and module design - it's not just a style preference but affects how your code can be used by others. --- ## Externalize configuration parameters Create configurations that can be easily managed outside your application code. Design configuration parameters to be externalized through appropriate mechanisms like environment variables, config files, or Kubernetes custom resources (CRs). This improves manageability, enables GitOps workflows, and supports different deployment environments. For Kubernetes-based applications, consider using Custom Resources to abstract complex configurations: ```yaml # Example: Using a custom resource for simplified configuration apiVersion: kubeflow.org/v2 kind: Profile metadata: name: ml spec: resourceQuotaSpec: hard: cpu: "2" memory: 2Gi requests.nvidia.com/gpu: "1" persistentvolumeclaims: "1" requests.storage: "5Gi" # Optional: Add LimitRange configurations here ``` Key practices: - Make configuration parameters like namespaces configurable rather than hardcoded - Document the implications of configuration choices, especially when they affect data persistence - Consider how configurations interact with mounted volumes or other external systems - Prefer configuration mechanisms that support auditability and automated deployment - Add ownership relationships to resources created from configurations to enable proper cleanup When handling package installation in environments like notebooks, be aware of how configuration choices affect persistence across restarts and different environments. --- ## Centralize dependency configurations When adding or updating package dependencies, place them in centralized configuration files rather than duplicating them across multiple services. Keep dependencies up-to-date with the latest stable versions and replace deprecated packages with their recommended successors. Always verify backward compatibility when upgrading dependency versions. Example for centralization: ```python # Instead of: # Adding to components/crud-web-apps/jupyter/backend/requirements.txt # kubernetes==v22.6.0 # Do this: # Update in components/crud-web-apps/common/backend/setup.py install_requires=[ "kubernetes>=22.6.0", # other dependencies ] ``` Example for replacing deprecated packages: ``` # Don't: kfserving==0.5.1 # deprecated package # Do: kserve==0.11.1 # recommended successor ``` --- ## Manage version constraints When configuring dependency version constraints in project files, follow these principles: 1. Be explicit about version ranges to balance flexibility with stability: - Allow minor version updates while preventing breaking changes - Example: `dependencies = ["huggingface_hub>=0.16.4,<1.0"]` instead of `<0.17` 2. Update interdependent packages together: - For packages that must be synchronized (like PyO3 and numpy), update them in tandem - Example: ```toml pyo3 = "0.16.2" numpy = "0.16.2" ``` 3. Separate dependency updates in version control: - Submit dependency updates in dedicated PRs rather than bundling them with other changes - This makes review and validation simpler, especially for detecting potential breaking changes --- ## Stable Public API Surface When modifying or adding exported interfaces in public headers, ensure the external API surface is stable, easy to use across platforms/languages, and does not leak internal implementation details. Apply these rules: 1) Platform-agnostic signatures: wrap OS/platform-specific details inside internal types/modules; the public API should not force callers to use different types/macros per platform. - Example pattern: ```cpp // public header class CpuSet; CpuSet get_cpu_thread_affinity_mask(int powersave); ``` 2) Consistent return types and lifetimes: prefer references to global/static data when the lifetime is guaranteed. - Example pattern: ```cpp // if the underlying object is always alive const CpuSet& get_cpu_thread_affinity_mask(int powersave); ``` 3) Integration-friendly API design: when there is an established de-facto API (e.g., OpenCV), prefer compatibility in names/semantics so drop-in usage is possible. 4) Public header encapsulation: do not expose internal helper/holder classes or implementation-only types in public headers—move them to source files or internal headers. 5) Cross-language linkage: for functions meant to be called from C/other languages, guard declarations and definitions with `extern "C"` under `__cplusplus`. - Example pattern: ```cpp #ifdef __cplusplus extern "C" { #endif void some_exported_c_function(void); #ifdef __cplusplus } #endif ``` Outcome: callers get one predictable API surface regardless of platform, language, or internal refactors—reducing integration breakage and preventing accidental exposure of internal implementation details. --- ## Inference Compatibility Rules Ensure layer math, parameter semantics, and model conversion/backends remain consistent so inference results don’t silently change. Apply these rules: - **Backward compatibility:** Do not change default parameter interpretation in a way that alters outputs for existing model files unless you provide a compatibility mechanism (e.g., versioned params) and tests. - **Convention correctness:** Follow the library’s established conventions for layer parameters (e.g., axis numbering). If multiple frameworks differ, translate explicitly at load/convert time. - **Numerical correctness:** Implement numerically sensitive formulas exactly (e.g., BatchNorm stability term belongs inside the sqrt when required). - **Conversion/runtime parity:** Conversion passes must only emit layers/operators that the runtime can execute. If the layer doesn’t exist yet, either implement it now or skip that conversion. - **Fast-path gating:** If an optimized path (packing/fast mode) isn’t fully implemented, disable it based on the controlling flag and **fall back** to the correct baseline implementation. Example pattern for fast-path gating: ```cpp int create_pipeline(const Option& opt) { if (opt.fast_gelu == 0) { support_packing = false; // disable incomplete fast/packing } return 0; } int forward_inplace(Mat& x, const Option& opt) const { if (opt.fast_gelu == 0) { // correct baseline implementation return GELU::forward(x, opt); } // otherwise run optimized path // ... return 0; } ``` These rules prevent silent output drift across AI inference workloads and keep model conversion reliable. --- ## Environment-aware configuration design {% raw %} Design configurations that work consistently across different environments without requiring environment-specific modifications. Configurations should be parameterized and adaptable to various deployment contexts (development, production, air-gapped environments). Key practices: - Avoid hardcoding environment-specific values - Parameterize configurations to accept values from environment variables - Consider accessibility constraints (like air-gapped environments) - Test configurations across different target environments For example, instead of: ```yaml # Only works in master branch with "latest" tag export CURRENT_CENTRALDB_IMG=docker.io/kubeflownotebookswg/centraldashboard:latest kustomize build overlays/kserve | kubectl apply -f - ``` Use a more flexible approach: ```yaml # Works across different branches and environments IMG=${{env.IMG}}:${{env.TAG}} kustomize build overlays/kserve | kubectl apply -f - kubectl patch deployment $DEPLOYMENT -n kubeflow --patch \ '{"spec": {"template": {"spec": {"containers": [{"name": "'"$CONTAINER"'","image": "'"$IMG"'"}]}}}}' ``` Additionally, for UI resources, consider providing configuration options that work in restricted network environments: ```yaml # Configurable options for different environments imageOptions: - source: internal # For air-gapped environments - source: external # For internet-connected environments ``` {% endraw %} --- ## centralize configuration constants Configuration values, constants, and default settings should be defined in a single location and referenced from there, rather than duplicated across multiple files or functions. This prevents inconsistencies, reduces maintenance burden, and ensures that changes to configuration values only need to be made in one place. When you find the same configuration value appearing in multiple locations, extract it to a shared constant or configuration object. For example: ```javascript // Bad - duplicated constant const workflow_count = 10; // in app.js // ...and the same value hardcoded elsewhere in ui.js // Bad - duplicated default value const delta = 0.025; // in one function let delta = localStorage.getItem("...") || "0.1" // different default elsewhere // Good - centralized configuration const CONFIG = { WORKFLOW_COUNT: 10, EDIT_ATTENTION_DELTA: 0.1 }; // Reference the centralized value const workflow_count = CONFIG.WORKFLOW_COUNT; let delta = localStorage.getItem("...") || CONFIG.EDIT_ATTENTION_DELTA; ``` This approach ensures that configuration changes are atomic and reduces the risk of inconsistent behavior across your application. --- ## Use modern assertions Always use current assertion methods in test code to ensure clarity and future compatibility. Specifically, replace deprecated methods with their modern equivalents, such as using `assertRaisesRegex` instead of `assertRaisesRegexp` when validating exceptions. This approach allows you to verify both the exception type and the specific error message content in a single assertion. ```python # Bad with self.assertRaisesRegexp(ValueError, "expected message"): function_that_raises() # Good with self.assertRaisesRegex(ValueError, "expected message"): function_that_raises() ``` By using modern assertion methods, you improve test readability and maintainability while ensuring your tests will continue to work with future framework updates. --- ## Semantic Collision-Safe Naming All identifiers should be (1) semantically clear, (2) consistent with project naming patterns, and (3) collision-safe. Apply this checklist: - Prefer clear, domain-meaningful names for configuration fields (avoid ambiguous terms like `resize_type` when the concept is “mode/sample_type”). - Prefer names like `mode` / `sample_type` and keep comments consistent with the chosen name. - For enum values, use explicit, scoped-like prefixes (especially when relying on C++11 enum scoping is optional). - Example: ```cpp enum InterpolationMode { Interpolation_BILINEAR = 1, Interpolation_Nearest = 2, Interpolation_BICUBIC = 3 }; ``` - Do not use leading underscore for member/attribute identifiers (e.g., avoid `int _axis`; use `int axis`). - Avoid non-English transliterations (e.g., don’t introduce identifiers using Chinese Pinyin when an English/technical term exists). - For macros/externally visible identifiers, always use project-qualified names to prevent collisions (e.g., replace `forceinline` with `NCNN_FORCE_INLINE`). Result: names communicate intent, remain consistent across the codebase, and won’t conflict with external code or platform headers. --- ## Remove debugging artifacts Production code should be free from debugging artifacts that reduce readability and maintainability. Remove all debugging print statements, commented-out code blocks, and other temporary debugging elements before merging code. Specifically: 1. **Remove all debugging print statements**: Debug prints should only appear in development branches or be wrapped in appropriate debug-only conditions. ```cpp // BAD: Unconditional debug printing sd_printf("Before op execution \n", 0); // GOOD: Conditional printing only when needed if (LOG_LEVEL >= DEBUG) { sd_printf("Before op execution \n", 0); } ``` 2. **Delete commented-out code**: Commented-out code creates confusion about which implementation is correct and clutters the codebase. ```cpp // BAD: Leaving commented-out code without explanation //REQUIRE_TRUE(expectedUpdShape == updShape, 0, "SCATTER_ADD OP: wrong shape of updates array..."); // GOOD: Either remove it entirely or provide a clear justification comment // REQUIRE statement intentionally disabled during beta testing until shape validation is fixed in issue #1234 //REQUIRE_TRUE(expectedUpdShape == updShape, 0, "SCATTER_ADD OP: wrong shape of updates array..."); ``` 3. **Clean up unused variables and redundant operations**: Remove variables that are declared but never used. If debugging functionality needs to be preserved for future troubleshooting, consider implementing proper logging with configurable levels rather than leaving print statements scattered throughout the code. --- ## Document non-obvious code Add clarifying comments to improve code readability and maintainability when code behavior isn't immediately obvious. Two key practices to follow: 1. **Label non-obvious function arguments** with the `/*arg=*/` prefix to clarify their purpose. This is especially important for boolean flags, magic numbers, or default values where the meaning isn't self-evident. Example: ```cpp // Poor: Parameters without context rescaled_type = uint8_type.clone(buildQTypeFromMinMax( builder, uint8_element_quant_type.getExpressedType(), builder.getF64FloatAttr(type_range_min), builder.getF64FloatAttr(type_range_max), builder.getI32IntegerAttr( uint8_element_quant_type.getStorageTypeIntegralWidth()), 0, true, builder.getBoolAttr(narrow_range))); // Better: Non-obvious arguments labeled rescaled_type = uint8_type.clone(buildQTypeFromMinMax( builder, uint8_element_quant_type.getExpressedType(), builder.getF64FloatAttr(type_range_min), builder.getF64FloatAttr(type_range_max), builder.getI32IntegerAttr( uint8_element_quant_type.getStorageTypeIntegralWidth()), /*bias=*/0, /*signed=*/true, builder.getBoolAttr(narrow_range))); ``` 2. **Provide detailed comments with examples** for complex code blocks. When implementing logic that's not immediately intuitive, include examples of inputs and expected outputs or describe the transformation being performed. For instance, when writing code that manipulates compiler include paths: ```cpp // This fixes include paths by also including paths where resolved symlinks are replaced // by the original paths. Example: // If cc returns "/usr/bin/gcc/lib/include" but the actual path is a symlink from // "/usr/lib/include", both paths will be included to ensure proper header resolution. ``` These documentation practices help other developers understand code intent without having to reverse-engineer the logic, reducing maintenance burden and preventing bugs during future modifications. --- ## Validate tensor inputs safely When handling tensor inputs that may contain invalid values, use transformational approaches rather than conditional checks. Conditional checks like `if value < 0:` may work with scalar values but fail with tensor objects during graph execution. Instead of raising exceptions based on conditions: ```python # Not tensor-friendly - may fail during graph execution if clip_norm < 0: raise ValueError('clip_norm should be positive') ``` Use transformations to handle invalid values: ```python # Tensor-friendly approach clip_norm = math_ops.maximum(clip_norm, 0) # Convert negative values to zero ``` For type validations, ensure you check all inputs comprehensively: ```python # Complete validation for both input and output types if (not dtype.is_floating and not dtype.is_integer) or (not image.dtype.is_floating and not image.dtype.is_integer): raise AttributeError('data type must be either floating point or integer') ``` When implementing such transformations, document the behavior clearly to inform users how edge cases are handled. --- ## Canonical Naming and Typos Use canonical, consistently formatted identifiers across code and build files, and verify every variable/option name is spelled exactly as the build system expects. Apply this checklist: 1) Canonical token per platform/arch: follow the established external style the project aligns with (e.g., for Loongarch, prefer `loongarch` consistently rather than `loongarch64` for directory/file/class naming). 2) Consistent formatting for feature/option names: follow existing project patterns for suffixes (e.g., prefer `NCNN_SSE41` over `NCNN_SSE4_1` to match conventions like `NCNN_ARM82`, `NCNN_ARM86XXX`). 3) Typo-proof build identifiers: for CMake, use the exact variable names (typos silently break behavior). Example (CMake): ```cmake # Bad (typo) set(CMAKE_EXECUTBLE_LINKER_FLAGS "${CMAKE_EXECUTBLE_LINKER_FLAGS} ...") # Good set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -s FORCE_FILESYSTEM=1") # Good option naming option(NCNN_SSE41 "optimize ... with sse4.1 extension" ON) ``` --- ## Consistent descriptive naming Maintain consistency in naming patterns across related resources while ensuring names accurately reflect their purpose. When naming components, files, or configurations: 1. Use the same naming pattern for related components (e.g., if using "pvcviewer" in labels, use "pvcviewer-" as prefix rather than "pvc-viewer-") 2. Choose names that precisely reflect the component's purpose (e.g., "test" rather than "check" for testing workflows) 3. Apply naming conventions consistently across configuration files, code, and documentation Example: ```yaml # Good namespace: kubeflow namePrefix: pvcviewer- # Consistent with label "pvcviewers" used elsewhere # Avoid namespace: kubeflow namePrefix: pvc-viewer- # Inconsistent with "pvcviewers" label ``` For workflow files, use names that accurately describe their function: ```yaml # Good name: CentralDashboard-angular Frontend Tests # filename: centraldb_angular_frontend_test.yaml # Avoid name: CentralDashboard-angular Frontend check # filename: centraldb_angular_frontend_check.yaml ``` --- ## Structured OWNERS files OWNERS files must follow project documentation standards to properly reflect component ownership and maintainership. When creating or updating these files: 1. List approvers who are actively driving the component and have explicitly agreed to participate 2. Do not duplicate people between approver and reviewer sections 3. Leave sections empty if there are no appropriate people to list rather than filling them incorrectly 4. Reference project guidelines for file structure (e.g., Kubeflow documentation standards) Example of a properly structured OWNERS file: ```yaml approvers: - developer1 - developer2 - developer3 reviewers: - reviewer1 - reviewer2 ``` If someone should be both an approver and a reviewer, only list them as an approver. This ensures clear documentation of component ownership and streamlines the review process. --- ## Secure infrastructure maintenance Maintain CI/CD infrastructure with security and currency as top priorities. This includes: 1. **Keep build tools updated**: Always use the latest stable versions of build tools and dependencies in CI/CD environments to benefit from bug fixes, security updates, and improved features. 2. **Never bypass security measures**: Security controls like package signature verification are essential and should never be disabled for convenience. Example from Discussion 1: ```dockerfile # GOOD: Keep signature verification enabled # Install packages securely RUN C:\tools\msys64\usr\bin\bash.exe -lc 'pacman --noconfirm -Syy git curl zip unzip patch' # BAD: Don't disable signature verification # RUN Add-Content -Path C:\tools\msys64\etc\pacman.d\mirrorlist.mingw32 -Value 'SigLevel = Never' # RUN Add-Content -Path C:\tools\msys64\etc\pacman.d\mirrorlist.mingw64 -Value 'SigLevel = Never' # RUN Add-Content -Path C:\tools\msys64\etc\pacman.d\mirrorlist.msys -Value 'SigLevel = Never' ``` Example from Discussion 0: ```dockerfile # GOOD: Use recent versions of build tools RUN (New-Object Net.WebClient).DownloadFile( 'https://github.com/bazelbuild/bazelisk/releases/download/v1.16.0/bazelisk-windows-amd64.exe', 'C:\tools\bazel\bazel.exe') # BAD: Don't use outdated versions # RUN (New-Object Net.WebClient).DownloadFile( # 'https://github.com/bazelbuild/bazelisk/releases/download/v1.11.0/bazelisk-windows-amd64.exe', # 'C:\tools\bazel\bazel.exe') ``` Regularly audit build environments to ensure they remain secure and up-to-date. Document version update procedures to make maintenance easier for the team. --- ## Maintain package verification Always keep signature verification enabled in package managers, even in development environments, Docker containers, or when facing initialization challenges. Disabling signature verification creates a significant security vulnerability by allowing potentially compromised or malicious packages to be installed. **Why this matters**: Package signature verification is a critical defense against supply chain attacks. Even temporary disabling for convenience can expose systems to compromise. **Example - Do not do this**: ```dockerfile # Disable signature checking on pacman because we cannot initialize the keyring RUN pacman-key --init && pacman -Sy --noconfirm --disable-download-timeout ``` **Instead do this**: ```dockerfile # Initialize keyring properly to maintain signature checking RUN pacman-key --init && pacman-key --populate && pacman -Sy --noconfirm --disable-download-timeout ``` When facing difficulties with package signature verification, research the proper initialization method rather than disabling the security feature. --- ## Document migration paths When implementing version changes or migrations, provide comprehensive documentation and tools to support users through the transition process. This includes: 1. Clearly identify and document breaking changes between versions 2. List specific dependencies required before and after migration 3. Provide step-by-step upgrade instructions with realistic expectations 4. Create migration tools with concrete usage examples For example, when creating a version converter tool: ``` # KfDef version converter ## Overview This is a simple helper CLI that converts KfDef between versions. ## Usage A simple CLI to convert KfDef from v1alpha1 to v1beta1 Usage: kfdef-converter [command] Available Commands: help Help about any command tov1beta1 Convert a KfDef config in v1alpha1 into v1beta1 format. ## Example # Convert a config file from v1alpha1 to v1beta1 kfdef-converter tov1beta1 --input=/path/to/old-config.yaml --output=/path/to/new-config.yaml ``` When planning roadmaps that include migrations, be specific about upgrade capabilities rather than making general promises. If complete migration support isn't feasible, consider defining limited scope migrations or marking them as stretch goals. --- ## Prioritize tokenizer simplicity When implementing AI model components like tokenizers, favor simplicity over rarely-used features that significantly increase code complexity. This is especially important for performance-critical paths in machine learning pipelines. Consider removing or deferring implementation of features that: 1. Require complex argument parsing 2. Are used only in specialized cases 3. Introduce significant maintenance burden Example: ```typescript // AVOID: Complex implementation with rarely-used features let encodeBatch = promisify(tokenizer.encodeBatch.bind(tokenizer)); var output = await encodeBatch( [["Hello, y'all!", "How are you 😁 ?"], ["Hello to you too!", "I'm fine, thank you!"]] ); // BETTER: Simplified implementation focusing on core functionality var output = await tokenizer.encodeBatch(["Hello, y'all!", "How are you 😁 ?"]); ``` This approach helps maintain performance in AI inference paths while keeping the codebase maintainable. Features can always be added later when there's a clear need and sufficient time for proper implementation. --- ## Private vulnerability reporting Never expose security vulnerabilities in public issue trackers. Security issues require confidential handling to prevent exploitation before fixes are available. Use private reporting channels such as: 1. A dedicated security email address (e.g., security@project.org) 2. GitHub's private vulnerability reporting feature When implementing security reporting processes: - Follow CNCF security templates for standardized procedures (https://github.com/cncf/tag-security/tree/main/project-resources) - Create clear documentation on how to report vulnerabilities - Establish a security response team with defined responsibilities Example security.md section: ```markdown ## Reporting a Vulnerability Please DO NOT report security vulnerabilities through public GitHub issues. Instead, please report them via: - Our dedicated security email: security@project.org - GitHub's private vulnerability reporting feature: [Project Security](https://github.com/organization/project/security/advisories/new) Include as much information as possible about the vulnerability. The security team will respond acknowledging receipt of the report and outline the next steps in handling your submission. ``` This practice helps protect users while vulnerabilities are being addressed and follows security industry best practices. --- ## Keep configurations current Ensure all configuration elements (dependencies, build settings, preprocessor flags) are up-to-date, documented, and consistent with project standards. This practice prevents issues arising from outdated references and improves maintainability for team members. Key practices include: 1. Document special configuration elements in README files or documentation: ``` // In NecAurora.md: // .vc/.vcpp file extensions are used to differentiate VE device files // from c/cpp in cmake. Cmake will compile them using nec. ``` 2. Update preprocessor definitions when dependencies change names or versions: ```cpp -#ifdef HAVE_MKLDNN +#ifdef HAVE_ONEDNN // Updated to reflect new dependency name ``` 3. Maintain consistent tool versions across related projects (e.g., same Maven version for all modules) 4. Verify third-party dependencies comply with organizational policies before inclusion, especially for licensing requirements Regularly audit configuration files to ensure they remain aligned with current technologies, dependency versions, and organizational standards. --- ## Use explicit assertions Tests should assert specific expected values rather than just verifying general functionality. This practice makes tests more robust against subtle regressions and helps catch "under the radar" bugs where behavior is modified unintentionally. Instead of print statements or simply checking that code runs without errors, include explicit assertions that verify exact expected outputs: ```rust // LESS ROBUST: Only verifies the code runs without errors #[test] fn test_tokenizer() { let output = tokenizer.encode("Hello", true).unwrap(); println!("{:?}", output.get_tokens()); // Just prints, doesn't verify } // MORE ROBUST: Explicitly checks expected values #[test] fn test_tokenizer() { let output = tokenizer.encode("Hello", true).unwrap(); assert_eq!( output.get_tokens(), ["[CLS]", "Hello", "[SEP]"] ); assert_eq!( output.get_ids(), [1, 27253, 2] ); } ``` This approach creates tests that serve as both verification and documentation of expected behavior. While it may require more maintenance when intentionally changing behavior, it significantly improves the ability to catch unintended changes and regressions. --- ## Standardize makefile patterns Maintain consistent Makefile patterns across all components to improve build reliability and developer experience in CI/CD pipelines. Key practices to follow: 1. Use `.PHONY` targets for all rules to prevent conflicts with actual files: ```makefile .PHONY: build docker-build docker-push image ``` 2. Standardize version tagging across components: ```makefile TAG ?= $(shell git describe --tags --always) ``` 3. Create consistent build rule patterns across components: ```makefile docker-build: docker build -t ${IMG}:${TAG} -f Dockerfile . docker-push: docker push ${IMG}:${TAG} image: docker-build docker-push ``` 4. Avoid changing directories in build commands when possible; use Docker's build context parameter instead: ```makefile # Instead of: # cd .. && docker build -t ${IMG}:${TAG} -f Dockerfile . # Prefer: docker build -t ${IMG}:${TAG} -f Dockerfile .. ``` 5. Remove unused or deprecated build rules to keep Makefiles maintainable. These standardized patterns make it easier for developers to work across different components, improve CI/CD pipeline reliability, and reduce confusion when building and deploying components. --- ## avoid hardcoded values Replace hardcoded styling values and configuration constants with flexible alternatives to improve maintainability and consistency. Use CSS variables for colors and theming, backend-provided values for limits and ranges, and semantic CSS properties instead of absolute positioning. Instead of hardcoding values: ```javascript // Avoid this divElement.style.backgroundColor = 'Black'; divElement.style.left = "20px"; divElement.style.position = "absolute"; max = 1920; // hardcoded limit ``` Use flexible alternatives: ```javascript // Prefer this divElement.style.backgroundColor = "var(--comfy-input-bg)"; divElement.style.cssFloat = "left"; divElement.style.marginRight = "4px"; max = targetWidget.options?.max; // use backend value ``` This approach makes code more maintainable by centralizing styling decisions, enables consistent theming across the application, and reduces the need to update multiple locations when requirements change. It also ensures that UI components adapt properly to different contexts and user preferences. --- ## Centralize dependency management Manage dependencies at the top level using `` to ensure version consistency across modules and prevent conflicts. Define version properties in one place and reference them throughout the project: ```xml 2.15.0 1.33 com.fasterxml.jackson.core jackson-databind ${jackson.version} io.netty netty-all ${netty.version} ``` In module pom files, reference dependencies without version numbers: ```xml com.fasterxml.jackson.core jackson-databind ``` Avoid: - Release candidate (RC) or SNAPSHOT versions in production code - Downgrading library versions - Using generic version references like `${project.version}` or `${project.parent.version}` - Different versions of the same underlying libraries (e.g., JavaCPP) For related but distinct libraries (like Netty 3.x vs 4.x), create separate version properties (e.g., `netty3.version` and `netty.version`) to clearly distinguish them. --- ## Use appropriate log levels Always match logging levels to the message's purpose and severity. Use log.Info for general information, log.Warn for warnings, and log.Error for error conditions. Avoid using fmt.Println for logging as it bypasses the logging framework's level-based filtering capabilities. Keep these guidelines in mind: - Start log messages with lowercase letters for consistency - Use the proper level that reflects the message's importance - Provide descriptive content in error messages that explains what went wrong Example of incorrect logging: ```go // Incorrect usage fmt.Println("Present working directory is: %v", cwd) log.Info("WARNING: Notebook container is not found, so could not update State of Notebook CR") ``` Example of correct logging: ```go // Correct usage log.Info("setting up workload identity", "ClientId", azure.AzureIdentityClientId) log.Error("could not find the notebook container", "notebook-name", instance.Name) ``` Following these practices helps with log filtering, improves troubleshooting, and creates a consistent logging experience throughout the codebase. --- ## Component-agnostic styling principles Create reusable components with styles that don't make assumptions about parent contexts or affect their positioning in different applications. Keep positioning styles (like margins) in the parent components that use them rather than in the reusable component itself. Prefer properties that don't assume parent styling context. **Instead of this:** ```scss // In a reusable component .panel-body { margin-top: 5px; // Affects positioning flex: 1; // Assumes parent has display: flex } ``` **Do this:** ```scss // In a reusable component .panel-body { padding: 1px; // Internal spacing only height: 100%; // Fills available space without assumptions } // In the parent component that uses it .parent-container .panel-body { margin-top: 5px; // Position-affecting styles belong here } ``` This approach ensures components remain flexible and can be reused in different contexts without layout issues. --- ## Private variable naming convention Use the 'prv' prefix for private class members and ensure they're explicitly declared with the 'private' access modifier. This maintains consistency with established team conventions and improves code readability by clearly indicating variable scope. ```typescript export class MyComponent { // Correct: prefix matches access modifier private prvUserData: UserData; // Incorrect: prefix doesn't match access modifier public prvConfig: Config; // Incorrect: no prefix but is private private userData: UserData; } ``` When refactoring existing code, update variable declarations to follow this pattern consistently. For observable patterns, public-facing properties should have clean names without implementation details while their corresponding subjects should use the 'prv' prefix: ```typescript export class MyService { // Private subjects private prvDataSubject = new ReplaySubject(1); // Public observable (clean naming) data = this.prvDataSubject.asObservable(); } ``` --- ## Match algorithms to purpose Select algorithmic constructs and control structures that are appropriate for the specific task. Common issues include: 1. Using loops when conditional checks are sufficient 2. Implementing overly complex traversal patterns for simple data structures 3. Missing edge cases in conditional logic that affect algorithm correctness For example, replace this inefficient nested loop approach: ```python # Unnecessarily complex traversal for condition in conditions: for item in condition: if "reason" in item: # process item ``` With a direct, more efficient approach: ```python # Simple, appropriate traversal for condition in conditions: if "reason" in condition: # process condition directly ``` Similarly, use `if` statements rather than `while` loops when you're only checking a condition once without repeated execution. This improves readability, prevents potential infinite loops, and better expresses the logical intent of your code. --- ## Type-appropriate default values Initialize variables with type-appropriate default values to prevent type errors and null reference exceptions during operations. When a variable is expected to hold a collection type (list, dictionary, set), use the corresponding empty collection (`[]`, `{}`, `set()`) rather than other falsy values like `None` or empty strings. For example, instead of: ```python conditions = notebook.get("status", {}).get("conditions", "") # Using "" as default for a variable that should be a list is problematic if some_condition: conditions.append(new_item) # This will fail if conditions is "" ``` Use type-appropriate defaults: ```python conditions = notebook.get("status", {}).get("conditions", []) # Using [] as default ensures the variable is always a list if some_condition: conditions.append(new_item) # This will work regardless ``` For complex data structures like dictionaries passed as parameters, consider adding type hints or documentation that clearly defines the expected structure, including which fields are optional vs. required. This helps prevent null reference errors when accessing dictionary keys. --- ## Use snake_case in Python Follow Python's PEP 8 naming convention by using snake_case for variables, functions, and methods rather than camelCase or other styles. This enhances readability and maintains consistency across the codebase. According to [PEP 8](https://peps.python.org/pep-0008/#descriptive-naming-styles), variable and function names in Python should use lowercase with words separated by underscores (snake_case). **Instead of writing:** ```python def set_notebook_memory(notebook, body, defaults): container = notebook["spec"]["template"]["spec"]["containers"][0] memory = get_form_value(body, defaults, "memory") memoryLimit = get_form_value(body, defaults, "memoryLimit") ``` **Write:** ```python def set_notebook_memory(notebook, body, defaults): container = notebook["spec"]["template"]["spec"]["containers"][0] memory = get_form_value(body, defaults, "memory") memory_limit = get_form_value(body, defaults, "memoryLimit") ``` This applies to all variable names, function names, method names, and module names in Python code. Class names should use CapWords (PascalCase) convention. --- ## Ensure test determinism Create reliable and reproducible tests by explicitly controlling test inputs and verifying function behavior doesn't have unintended side effects. Two key practices to follow: 1. When testing functions that shouldn't modify input parameters, verify the inputs remain unchanged: ```java // Before function call INDArray duplicateInput = inputMatrix.dup(); // Call function under test PCA.pca_factor(inputMatrix, ...); // Verify input wasn't modified assertEquals(duplicateInput, inputMatrix); ``` 2. Make tests deterministic by setting explicit seeds for any operations involving randomness: ```java // Use a specific seed to ensure deterministic behavior MultiLayerConfiguration conf = new NeuralNetConfiguration.Builder() .seed(2021) // Important: ensures consistent initialization for tests .dataType(DataType.DOUBLE) // other configuration .build(); ``` Including these practices in your tests will help prevent flaky tests, make debugging easier, and ensure that test failures represent actual issues rather than side effects or randomness. --- ## API structure balance Maintain a clear separation between resource-specific API handlers and common utilities. Resource-specific handlers should remain in their dedicated modules to reduce dependencies, while common functionality should be extracted into shared helpers for consistency. Example: ```python # GOOD: Common helper function in a shared utility file # components/crud-web-apps/common/backend/kubeflow/kubeflow/crud_backend/helpers.py def get_age(k8s_object): """Return age information in a standardized format for any k8s object.""" creation_time = dt.datetime.strptime( k8s_object["metadata"]["creationTimestamp"], "%Y-%m-%dT%H:%M:%SZ") uptime = dt.datetime.now() - creation_time return { "uptime": str(uptime).split('.')[0], # Remove microseconds "timestamp": creation_time.strftime("%Y-%m-%dT%H:%M:%SZ") } # GOOD: Resource-specific handlers in dedicated modules # components/model-web-app/backend/app/routes/inference_service.py def list_inference_services(namespace): """Handler specific to InferenceService resources.""" # Implementation specific to this resource type ``` This approach prevents common code from accumulating resource-specific dependencies while still promoting reuse of utility functions that apply across multiple API endpoints. When designing APIs, always evaluate whether functionality belongs in shared utilities or should remain in resource-specific implementations. --- ## Reduce nesting depth Improve code readability by reducing nesting depth with early returns and functional approaches. Use early returns to handle edge cases first, and prefer functional operators over nested conditionals when working with streams or collections. Example for early return: ```typescript // Instead of this selectType(event): void { this.typeSelected = event.value; if (this.typeSelected === 'New') { this.volume.controls.name.setValue(this.currentVolName); } } // Prefer this selectType(event): void { this.typeSelected = event.value; if (this.typeSelected !== 'New') return; this.volume.controls.name.setValue(this.currentVolName); } ``` Example for functional approach: ```typescript // Instead of this this.router.events.subscribe(event => { if (event instanceof NavigationEnd) { // Do something } }); // Prefer this this.router.events .pipe(filter(event => event instanceof NavigationEnd)) .subscribe(event => { // Do something }); ``` --- ## Safe URL operations When handling URLs for API interactions and navigation, use precise methods for both comparison and construction to avoid subtle bugs: 1. For URL path comparison, use `startsWith()` instead of `includes()` to prevent false positives from substring matches: ```typescript // AVOID: May lead to incorrect matches return browserUrl.includes(url); // BETTER: More precise path matching return browserUrl.startsWith(url); ``` 2. When constructing URLs, use the URL constructor with proper base parameter rather than manual string concatenation: ```typescript // AVOID: Potential issues with relative paths const href = window.location.origin + url; const urlObject = new URL(href); // BETTER: Robust URL construction const urlObject = new URL(url, window.location.origin); ``` These practices ensure reliable API interactions and prevent navigation edge cases when handling routes and endpoints. --- ## Use appropriate logging levels Reserve logging statements for their appropriate purposes and levels. Use debugging-level logs (`sd_debug`) for development-time diagnostic information, and only use standard printing functions (`sd_printf`) for critical user-facing messages or error conditions. Excessive or incorrectly leveled logging creates noise in production systems and can impact performance. Bad example: ```cpp // Inappropriate for normal operation flow sd_printf("Setting input buffer %d\n", index); sd_printf("Pushing variable\n", 0); sd_printf("realdiv: Pre variables\n", 0); ``` Good example: ```cpp // For diagnostic information during development sd_debug("Setting input buffer %d\n", index); sd_debug("Pushing variable\n"); // For error conditions that users need to see if(ptr == nullptr) sd_printf("ERROR: Context pointer is null!\n"); ``` Consistent logging practices improve code readability, aid in debugging, and prevent log pollution in production environments. --- ## Use enums for state When handling nullable or undefined states, use enumerations instead of primitive types like boolean or null/undefined. Enums provide more descriptive and type-safe representations of different states, including the absence of a value or an unknown state. Instead of: ```typescript private dashboardConnectedSource = new BehaviorSubject(true); ``` Use an enum to explicitly represent all possible states: ```typescript enum DashboardState { Unknown = 0, // Initial state before connection status is determined Connected, Disconnected, } private dashboardStateSource = new BehaviorSubject(DashboardState.Unknown); ``` This approach prevents misleading default values, improves code readability, and provides better type safety. When making decisions based on state, the enum forces you to handle all possibilities, reducing the likelihood of bugs related to unexpected null or undefined values. --- ## Normalize URL paths When handling URLs in web applications, consistently normalize path formats to prevent routing and service communication issues. This is especially important when working with services like Istio that expect specific URL formats (e.g., trailing slashes). Key implementation practices: 1. Ensure URLs end with trailing slashes when required by services 2. Create utility functions to normalize URL paths before comparison 3. Document URL format requirements in code comments Example: ```typescript // Ensure trailing slash for service URLs that require it (e.g., Istio) function normalizeServiceUrl(url: string): string { return url?.endsWith('/') ? url : url + '/'; } // When comparing URLs, normalize paths first function equalUrlPaths(firstUrl: string, secondUrl: string): boolean { // Handle sometimes missing '/' from URLs for consistent comparison const normalizedFirst = firstUrl?.endsWith('/') ? firstUrl : firstUrl + '/'; const normalizedSecond = secondUrl?.endsWith('/') ? secondUrl : secondUrl + '/'; return normalizedFirst === normalizedSecond; } ``` --- ## Compare floating-point safely When implementing numerical algorithms, never compare floating-point values directly for equality due to precision errors. Instead: 1. Use an epsilon threshold for comparisons: ```java private static final double EPSILON = 1e-6; // Choose appropriate precision // Instead of this: if (backpropGradient == 0.0) { ... } // Do this: if (Math.abs(backpropGradient) < EPSILON) { ... } ``` 2. For equality comparisons in algorithms like sorting or searching, use built-in methods: ```java // Instead of manually comparing with multiple conditions: if (lhs.fitness < rhs.fitness) return 1; else if (rhs.fitness < lhs.fitness) return -1; return 0; // Use the built-in compare method: return Double.compare(rhs.getFitness(), lhs.getFitness()); ``` 3. Choose appropriate epsilon values based on your application domain: - For double precision: typically 1e-6 to 1e-12 - For machine learning: often 1e-5 to 1e-7 - For financial calculations: may require stricter precision 4. In tests, be explicit about data types when comparing arrays to avoid hidden type conversion issues. Following these practices prevents subtle bugs in sorting, searching, and numerical algorithms where small differences in representation can lead to incorrect results. --- ## Flexible tokenizer implementation When implementing tokenizers for AI models, ensure flexibility and robust behavior across different contexts: 1. Initialize tokenizers with all relevant parameters to maintain consistent behavior: ```python tokenizer = Tokenizer(BPE( unk_token=str(unk_token), dropout=dropout, end_of_word_suffix=suffix )) ``` 2. Use flexible patterns for detecting special tokens (like unknown tokens) rather than hardcoded strings: ```python # Instead of checking for exactly "[UNK]" unk_token_regex = re.compile('(.{1}\b)?unk(\b.{1})?', flags=re.IGNORECASE) ``` This approach ensures tokenizers work consistently across different implementations and models, which is critical for reliable AI text processing pipelines and model interoperability. --- ## Precise workflow triggers Configure CI/CD workflows to trigger precisely based on relevant file path changes. This minimizes unnecessary builds and tests while ensuring all required workflows run when dependencies are modified. **For component-specific workflows:** - Include both direct component paths and shared dependencies - For web applications, include common library paths ```yaml # Example for a web application workflow name: Build & Publish JWA Docker image on: push: branches: - master - v*-branch paths: - components/crud-web-apps/jupyter/** # Component code - components/crud-web-apps/common/** # Shared dependencies ``` **For manifest-related workflows:** - Target only specific manifest directories rather than all component files ```yaml # For manifest testing, specify manifest paths only name: Build Profile Controller manifests on: pull_request: paths: - components/profile-controller/config/** # Only manifest changes ``` Centralize build logic in Makefiles instead of duplicating in GitHub Actions. This allows workflows to simply call make targets, making pipelines more maintainable and consistent across environments. --- ## Standardize style scripts Maintain consistent code style enforcement scripts across all projects by standardizing linting and formatting configurations in package.json. Use modern, supported tools instead of deprecated ones (like tslint). Every frontend project should include these standard scripts: ```json { "scripts": { "lint-check": "ng lint", "lint": "ng lint --fix", "format:check": "prettier --check 'src/**/*.{js,ts,html,scss,css}' || node scripts/check-format-error.js" } } ``` This approach ensures: 1. Consistent style enforcement across repositories 2. Both checking capabilities (`lint-check`, `format:check`) and auto-fixing options (`lint`) 3. Developer-friendly error messages when formatting fails 4. Alignment with established patterns in other repositories like Katib When adding these scripts, make appropriate configurations in angular.json as needed to support them. --- ## Automate style enforcement Configure your development environment to automatically enforce code style standards rather than relying on manual checks during code review. This includes: 1. Use modern, actively maintained linting tools instead of deprecated ones (e.g., replace tslint with eslint) 2. Configure your IDE to automatically apply formatting rules, such as adding newlines at end of files Example IDE configuration for VSCode (settings.json): ```json { "files.insertFinalNewline": true, "editor.codeActionsOnSave": { "source.fixAll.eslint": true } } ``` This approach reduces style-related comments in code reviews, ensures consistency across the codebase, and allows reviewers to focus on more substantive issues. --- ## Descriptive consistent naming Use descriptive and consistent names throughout the codebase. Prefer full, meaningful names over acronyms or abbreviations to improve readability and understanding, especially for newcomers. Maintain naming consistency across different files, configurations, and references to the same entity. Examples: - Prefer `centraldashboard-angular` over `centraldashboard` when referring to the Angular version of the central dashboard - Use `Access Management` instead of `KFAM` to clearly indicate the component's purpose When introducing new components or refactoring existing ones, ensure the same naming pattern is followed in all references to maintain consistency and avoid confusion. This includes Makefiles, configuration files, documentation, and code comments. --- ## Specific network access documentation When documenting network access methods or service connections, always provide specific commands with explicit ports and namespaces rather than general approaches. Include clear examples of how to connect to each required service and explain the underlying proxying mechanisms. For example, instead of general instructions like: ``` To access the Kubernetes REST API, run kubectl proxy --port=8083. ``` Provide specific commands for each service: ``` To access a Kubernetes service, run `kubectl port-forward -n kubeflow svc/ :` e.g. `kubectl port-forward -n kubeflow svc/jupyter-web-app-service 8085:80`. ``` Additionally, document how proxying works and what happens if network connections fail, including any potential cascade effects on dependent services. This specificity helps developers understand exactly what networking configurations are needed and prevents confusion when setting up local development environments or troubleshooting connection issues. --- ## Optimize container build configurations Configure containerized application builds to be efficient and flexible by avoiding hardcoded architecture decisions and using appropriate compiler flags. Let the build system determine architecture targeting instead of maintaining architecture-specific code blocks in your Dockerfiles. For Go applications, use appropriate build flags like `CGO_ENABLED=0` to enable static linking and optimize container images. **Example:** Instead of: ```dockerfile RUN if [ "$(uname -m)" = "aarch64" ]; then \ CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o webhook -a . ; \ else \ CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o webhook -a . ; \ fi ``` Prefer: ```dockerfile RUN CGO_ENABLED=0 GOOS=linux go build -o webhook -ldflags "-w" -a . ``` This approach simplifies maintenance, allows multi-architecture builds through tools like Docker buildx (e.g., `docker buildx build --platform linux/amd64,linux/arm64 ...`), and produces more efficient container images. --- ## Validate model optimization When implementing AI model optimization techniques such as early stopping algorithms or hyperparameter tuning, include proper validation mechanisms to help users effectively reduce model overfitting and improve accuracy. Validation should include: 1. Pre-execution checks on algorithm settings and configurations 2. Meaningful error messages for incorrect parameter ranges or incompatible settings 3. Documentation that explains the impact of each optimization technique For example, when implementing early stopping validation for Katib experiments: ```yaml # Example validation for early stopping settings algorithm: earlyStoppingSettings: # Validate these values with appropriate ranges and types evaluationInterval: 1 # Validate this is a positive integer threshold: 0.01 # Validate this is a positive float comparisonType: "smaller" # Validate this is one of ["smaller", "larger"] ``` This approach helps prevent common errors in machine learning workflows, reduces debugging time, and improves model quality by ensuring optimization techniques are correctly applied. --- ## Prefer external configuration Design applications to use external configuration sources rather than hardcoding values directly in source code. This allows for configuration changes without requiring code modifications or redeployment. When defining configurations that might change between environments or user preferences: - Use mechanisms like ConfigMaps, environment variables, or properly namespaced storage keys - Consider future extensibility in configuration design - Prefer dynamic configuration that can be updated without code changes For example, instead of hardcoding allowed namespaces: ```javascript // Avoid this export const ALL_NAMESPACES_ALLOWED_LIST = ['jupyter']; // Prefer dynamic configuration loaded from an external source export const ALL_NAMESPACES_ALLOWED_LIST = loadFromConfigMap('namespaces.allowed'); ``` Similarly, when importing resources to support configurable features, consider importing complete libraries if it enables easier configuration through external sources: ```javascript // This allows for configurable icons via ConfigMap without source code changes import '@polymer/iron-icons/communication-icons.js'; ``` --- ## Robust workflow configurations Ensure CI/CD workflow configuration files follow best practices for maintainability and correctness: 1. Use centralized dependency management approaches like setup tools extras instead of hardcoding dependencies in workflow files: ```python # Better approach (in setup.py): extras_require = { "dev": ["black==22.3", "click==8.0.4"] } # Then in workflow file: pip install package[dev] # Instead of: pip install black==22.3 click==8.0.4 ``` 2. Always quote numerical values in YAML files to prevent parsing issues, especially for version numbers: ```yaml # Correct: python: ["3.7", "3.8", "3.9", "3.10"] # Problematic: python: [3.7, 3.8, 3.9, 3.10] # 3.10 will be parsed as 3.1 ``` --- ## Consistent logging format Use consistent string formatting in logging statements throughout the codebase. Prefer `%` style placeholders over f-strings or `.format()` in logging calls as this is more efficient when logs are filtered by level (placeholders are only evaluated if the log is actually emitted). For good logging practices: 1. Use placeholder style consistently: ```python # Recommended logging.info('%s benchmark running.', operation_type) # Avoid mixing styles in the same codebase logging.error('No models found in S3 bucket: {}'.format(bucket_name)) logging.warning(f'Failed to process {item_name}') # Avoid f-strings in logging ``` 2. Reduce duplicate logging logic: ```python # Instead of: if opt.train: logging.info('%s training benchmark.', cell) else: logging.info('%s inference benchmark.', cell) # Prefer: mode = 'training' if opt.train else 'inference' logging.info('%s %s benchmark.', cell, mode) ``` 3. Choose appropriate log levels based on severity: - Use `logging.error()` for failures that prevent normal operation - Use `logging.warning()` for potential issues that don't stop execution - Use assertions only for developer-facing invariants that should never be violated - Consider warnings instead of assertions in user-facing code --- ## Use table-driven tests In Go, prefer table-driven tests over multiple separate test functions. Table tests allow for concise testing of multiple scenarios, improve code readability, and make it easier to add new test cases. A table-driven test consists of: 1. A slice of test cases, each containing input and expected output 2. A loop that executes the same test logic for each case 3. Clear error messages that identify which test case failed Example: ```go func TestSomething(t *testing.T) { tests := []struct { name string input map[string]string expected map[string]string }{ { name: "case1", input: map[string]string{"key1": "value1"}, expected: map[string]string{"key1": "value1", "defaultKey": "defaultValue"}, }, { name: "case2", input: map[string]string{}, expected: map[string]string{"defaultKey": "defaultValue"}, }, } for _, test := range tests { t.Run(test.name, func(t *testing.T) { result := functionUnderTest(test.input) if !reflect.DeepEqual(result, test.expected) { t.Errorf("Expected:\n%v\nGot:\n%v", test.expected, result) } }) } } ``` This pattern makes your test suite more maintainable and encourages thorough testing of edge cases by making it trivial to add new scenarios. When reviewing code, ensure new functionality is tested with table-driven tests rather than creating separate test functions for related scenarios. --- ## Simplify code structure Strive to simplify code structure by eliminating unnecessary complexity. This includes: 1. **Move conditions higher in the code** when appropriate to avoid unnecessary operations. Check conditions as early as possible to fail fast or skip work. ```go // Bad if (someCondition) { // do work } if err := r.Update(ctx, profileIns); err != nil { return err } // Good if (someCondition) { // do work if err := r.Update(ctx, profileIns); err != nil { return err } } ``` 2. **Avoid unnecessary conditionals** that don't change program behavior. ```go // Bad if !ok || existingValue != v { ns.Labels[k] = v } // Good ns.Labels[k] = v ``` 3. **Simplify complex if statements** by using early returns or continue statements to reduce nesting. ```go // Bad if pod.Status.ContainerStatuses[i].Name == instance.Name && pod.Status.ContainerStatuses[i].State != instance.Status.ContainerState { // handle condition } // Good if pod.Status.ContainerStatuses[i].Name != instance.Name { continue } if pod.Status.ContainerStatuses[i].State == instance.Status.ContainerState { continue } // handle condition ``` 4. **Reduce nesting** by checking negative conditions first and returning early. ```go // Bad if nodename != "" { // lots of code here } // Good if nodename == "" { return nil } // lots of code here with less indentation ``` 5. **Reuse existing functions** instead of creating new ones with similar functionality. This makes your code more readable, maintainable, and less error-prone. --- ## Check before use Always validate that objects, maps, and other reference types are non-nil before attempting to use them. Use early nil checks with clear returns to improve code readability and prevent null pointer exceptions. For objects: ```go // Good: Early nil check with informative logging if pod == nil { log.Info("No pod found. Won't update notebook conditions and containerState") return status, nil } // Now safely use pod... ``` For maps and collections: ```go // Good: Initialize map if nil before adding items if currSA.Annotations == nil { currSA.Annotations = map[string]string{} } currSA.Annotations[key] = value ``` This pattern reduces nesting levels, makes error conditions explicit, and prevents the most common source of runtime panics in Go. When functions receive objects from external sources or other functions, always check their validity before proceeding with operations on them. --- ## Technical precision matters When documenting AI models, frameworks, and optimization techniques, precision in language is as important as precision in your algorithms. Technical inaccuracies or unclear explanations can lead to implementation errors and confusion. Key practices to follow: 1. Use precise terminology when describing AI operations like quantization, operator fusion, and model optimization: - Be specific about performance impacts: "With quantized model there is a tiny accuracy drop, however this is the cost of great performance optimization and memory footprint reduction." - Clearly explain technical processes: "Last stage of quantization flow is to perform additional operator fusion." 2. Ensure grammatical correctness, especially when explaining causality in AI systems: - Incorrect: "find operator which mostly influence accuracy drops" - Correct: "find operator, which caused the most significant accuracy drop" 3. Maintain consistency in technical descriptions: - Use correct library names and conventions (e.g., oneDNN not ONEDNN) - Be consistent with framework terminology across documentation 4. Use appropriate articles and prepositions in technical explanations: - Incorrect: "INC allows automatically find better solution" - Correct: "INC allows to automatically find better solution" Clear documentation directly impacts how effectively developers can implement and optimize AI models, particularly for critical operations like quantization that balance accuracy and performance. --- ## Simplify for readability Complex expressions, especially nested ternary operations, reduce code readability and maintainability. Prefer simpler alternatives: 1. Break down nested ternary operations into clear if-else statements: ```cpp // Hard to read: TBlob temp_mid_tblob = ((common::is_int(inputs[0].type_flag_) || inputs[0].type_flag_ == kBool) && !param.exp_is_int) ? outputs[0] : inputs[0].type_flag_ == kBool ? TBlob(...) : inputs[0]; // More readable: if ((common::is_int(inputs[0].type_flag_) || inputs[0].type_flag_ == kBool) && !param.exp_is_int) { temp_mid_tblob = outputs[0]; } else if (inputs[0].type_flag_ == kBool) { temp_mid_tblob = TBlob(...); } else { temp_mid_tblob = inputs[0]; } ``` 2. Simplify boolean conditions and remove unnecessary parentheses: ```cpp // Instead of: const bool same_shape = (inputs[0].shape() == inputs[1].shape()); // Use: const bool same_shape = inputs[0].shape() == inputs[1].shape(); ``` 3. Store frequently referenced values in well-named variables: ```cpp // Extract shapes used multiple times const auto& lhs_shape = inputs[0].shape(); const auto& rhs_shape = inputs[1].shape(); const bool same_shape = lhs_shape == rhs_shape; ``` 4. Define constants for magic numbers instead of using literals: ```cpp // Instead of: const auto softrelu = (val > 20) ? val : ::log(1 + ::exp(val)); // Define a constant: const float SOFTRELU_THRESHOLD = 20.0f; const auto softrelu = (val > SOFTRELU_THRESHOLD) ? val : ::log(1 + ::exp(val)); ``` 5. Use const for loop iterators and function parameters when they're not modified: ```cpp // Prefer: for (const auto& kv : n.outputs) { // code } ``` These practices improve code clarity, reduce cognitive load when reading the code, and make future maintenance easier. --- ## Explain optimization mechanisms When implementing or documenting performance optimizations, clearly explain the mechanism and expected performance benefit. For memory-bound optimizations, specify exactly how memory operations are reduced: ```python # Instead of: out_mem = conv_result # Requires writing to output memory activation_layer(out_mem) # Requires reading and writing again # Better (fusion): out_mem = activation_layer(conv_result) # Single memory write # For additive operations: # Instead of: out_mem = conv_result # Overwrites existing data # Better: out_mem += conv_result # Adds to existing data without separate read ``` For data-intensive operations like quantization tuning, include preparation best practices: "As input data is used many times during tuning, it is better to have it prepared earlier." This reduces redundant processing and improves overall performance. When explaining optimization patterns, clearly describe the benefit: "chaining operations which can be performed one after another immediately, where input of every subsequent operation is the output of the previous one" provides specific insight into why the optimization helps. Precise explanations help developers implement optimizations correctly and make informed decisions about performance trade-offs. --- ## Pre-compute reused data When data will be accessed multiple times during processing, avoid redundant calculations by pre-computing values upfront rather than using lazy evaluation. This pattern significantly improves performance in iterative operations like machine learning training, inference, or repeated data transformations. For example, in data processing pipelines: ```python # Performance optimization: # Pre-compute transformations when data will be accessed repeatedly transformer = transforms.Compose([ transforms.Resize(256), transforms.CenterCrop(224), transforms.ToTensor(), transforms.Normalize(mean=rgb_mean, std=rgb_std) ]) # Use lazy=False to prepare data upfront when it will be used multiple times data_loader = DataLoader(dataset.transform_first(transformer, lazy=False)) ``` By preparing data once rather than on-demand, you reduce computational overhead and improve overall execution speed, especially in performance-critical sections of code. --- ## Reliable Technical Documentation When updating technical docs, ensure they are reliable in both what they claim and how developers can apply them: - Keep headings/sections aligned with the exact runtime/build parameters shown in outputs (e.g., if the benchmark runs with gpu_device=0, reflect “GPU0” in the subsection title). - Express requirements as constraints when that’s what’s true (e.g., “CMake >= 3.10” rather than only “CMake 3.10”) and update wording if other tested versions work. - For troubleshooting, provide a complete, actionable flow: clear cause(s), prerequisites (what to install), concrete commands to run, and warnings about common pitfalls (e.g., avoid installing protobuf into system paths if it breaks version resolution). - Use robust Markdown for plain URLs—wrap raw links in angle brackets to reduce rendering issues: ```md 参考： ``` Practical checklist before merging a doc change: 1) Do section titles/subtitles match the commands and parameters in the text? 2) Are version statements accurate (use >= or range when appropriate)? 3) Can someone follow the steps from a clean environment to a working result? 4) Are there cautions for known failure modes (path conflicts, mismatched shared libraries)? 5) Do external links render consistently in Markdown? --- ## Config Contract Enforcement When introducing or updating environment/configuration behavior, ensure the documented meaning, runtime inputs (CLI/feature flags), and build-time discovery (CMake/pkg paths) all point to the same intended target. Avoid “it compiles” success that doesn’t enable the feature, and avoid “it builds” that accidentally links against a mismatched dependency set. Apply this checklist: 1) Runtime flags must match documentation semantics - If a config value means “disabled” (e.g., `gpu_device = -1`), do not report results or behavior as if the feature were enabled. Ensure the corresponding benchmark/runtime command-line option actually enables it. 2) Build-time dependency resolution must be anchored to an explicit prefix - Install dependencies to a dedicated directory via `--prefix`. - In CMake, set `CMAKE_PREFIX_PATH` to paths under that prefix (so bin/lib/include match) BEFORE `find_package`. Example (CMake prefix configuration): ```cmake # e.g., /path/to/protobuf/install set(ProtobufRoot "/path/to/protobuf/install") # Point CMake to the exact install root’s artifacts list(APPEND CMAKE_PREFIX_PATH "${ProtobufRoot}/bin" "${ProtobufRoot}/lib" "${ProtobufRoot}/include") find_package(Protobuf REQUIRED) ``` If configuration involves both build and runtime, verify end-to-end: the build-time selection (what got found/linked) and the runtime enablement (what got switched on) are consistent with the docs and expected behavior. --- ## Use intent-revealing names Choose names that clearly reveal the purpose, behavior, or type of the code elements they represent. A good name should answer "what" rather than "how" and should be precise enough to avoid ambiguity. For functions, choose names that indicate what they do or return: ```cpp // Less clear inline bool is_float(const int dtype) { // checks if dtype is any floating point type } // More clear inline bool is_floating(const int dtype) { // clearly indicates checking for any floating point type } ``` For variables, use domain-specific terms that express their meaning: ```cpp // Less clear const int strides_1 = floor((IH << 1) / OH) - floor(IH / OH); const int strides_2 = floor((IW << 1) / OW) - floor(IW / OW); // More clear const int strides_H = floor((IH << 1) / OH) - floor(IH / OH); const int strides_W = floor((IW << 1) / OW) - floor(IW / OW); ``` Use prefixes or qualifiers when name conflicts might occur: ```cpp // Potential conflict with mshadow::kInt8 enum QuantizeOutType { qAuto = 0, qInt8, qUint8 }; ``` For configuration variables, be specific about what they control: ```cpp // Too generic bool disable_fuse_all = dmlc::GetEnv("MXNET_DISABLE_ONEDNN_FUSE_ALL", false); // More specific bool disable_fuse_requantize = dmlc::GetEnv("MXNET_DISABLE_ONEDNN_FUSE_REQUANTIZE", false); bool disable_fuse_dequantize = dmlc::GetEnv("MXNET_DISABLE_ONEDNN_FUSE_DEQUANTIZE", false); ``` Extract meaningful operations into well-named functions instead of using inline code blocks. --- ## Pin version dependencies Explicitly pin version dependencies in configuration files to ensure reproducible builds and prevent breaking changes. When dealing with external tools, scripts, or APIs, always specify exact versions or commit hashes rather than using "latest" or master branches. Examples: ```makefile # Good: Pin external scripts to specific commit hashes test -f ${ENVTEST_ASSETS_DIR}/setup-envtest.sh || curl -sSLo ${ENVTEST_ASSETS_DIR}/setup-envtest.sh https://raw.githubusercontent.com/kubernetes-sigs/controller-runtime/a9bd9117a77a2f84bbc546e28991136fe0000dc0/hack/setup-envtest.sh # Good: Specify exact versions of tools $(call go-get-tool,$(CONTROLLER_GEN),sigs.k8s.io/controller-tools/cmd/controller-gen@v0.8.0) ``` When managing cross-version compatibility, add clear documentation for when temporary compatibility configurations can be removed: ```yaml # Good: Document temporary compatibility settings spec: preserveUnknownFields: false # TODO: Remove in Kubeflow 1.7 release ``` For build configurations, explicitly define the environment to ensure consistency: ```makefile # Setting SHELL to bash allows bash commands to be executed by recipes SHELL = /usr/bin/env bash -o pipefail .SHELLFLAGS = -ec ``` Regularly clean up unused dependencies with tools like `go mod tidy` to maintain clean configuration files. --- ## Documentation clarity and formatting When writing documentation (README files, tutorials, API docs), ensure clarity and proper formatting: 1. **Define technical terms and concepts** - Don't assume readers are familiar with specialized terminology. Include brief explanations and relevant links for reference. ```markdown # Arguments - batch_size: Define batch size (default=64) - epochs: Define total epochs (default=1000) - mu: Define μ in μ-Law encoding for audio quantization (see https://en.wikipedia.org/wiki/μ-law_algorithm) ``` 2. **Understand markdown formatting rules** - Be aware that formatting details like trailing spaces affect rendering. Double spaces at line ends create line breaks in markdown. 3. **Preview rendered output** - Always check how documentation will actually appear to users before committing changes. 4. **Keep technical references current** - When documenting code structures, ensure descriptions match the actual implementation. Update documentation when code interfaces change. Following these practices ensures documentation is both technically accurate and genuinely helpful to other developers. --- ## Descriptive error context Error messages should be specific, descriptive, and include context to help with debugging. Avoid generic messages like "Failed execution" or numeric error codes without explanation. Key principles: 1. Always include the class/method name in error messages: `ShapeList::push_back: ShapeList limit exceeded` 2. Provide relevant variable values and expected conditions: `Expected type FLOAT32, but got INT32` 3. Use explicit errors for edge cases rather than silent handling 4. Format complex data types in human-readable form Example with improved error messaging: ```cpp // Poor error message if (size() <= idx || idx < 0) throw std::runtime_error("Can't find requested variable by index"); // Better error message if (size() <= idx || idx < 0) throw std::runtime_error( std::string("ShapeList::at: Index out of bounds, requested: ") + std::to_string(idx) + " but size is: " + std::to_string(size()) ); ``` For assertions in lower-level code that might be called from higher-level languages like Java, include descriptive messages that don't require reading C++ code to understand the error condition. --- ## Explicit null checks Always use explicit null checks (`value is None` or `value is not None`) rather than implicit truthiness evaluations when testing for null/None values. Implicit boolean checks can invoke `__bool__` methods leading to unexpected behavior. **Do this:** ```python # Explicitly check if out is not None if out is not None: # Use out process(out) ``` **Not this:** ```python # Don't rely on truthiness which may call __bool__ if out: # May not behave as expected if __bool__ is implemented process(out) ``` For complex types that can represent optional values, use proper optional type wrappers: In C++: ```cpp // Use optional wrappers for nullable types 'float or None': 'dmlc::optional' // Instead of just 'mx_float' ``` When handling values that might have multiple return types or be null: ```python # Check the specific type before processing if isinstance(out, NDArrayBase): return out return list(out) # Convert if needed ``` --- ## Validate and document nulls Always handle null values explicitly and consistently throughout your codebase to prevent null pointer exceptions. Follow these guidelines: 1. **Validate nulls early** using Preconditions to provide clear error messages: ```java // Use explicit null checks with informative messages Preconditions.checkNotNull(input, "Input cannot be null"); Preconditions.checkArgument(shape != null && shape.length > 0, "Invalid shape: %s", shape); ``` 2. **Document null behavior** clearly in Javadoc comments: ```java /** * Creates a buffer in the specified workspace. * @param workspace Optional memory workspace to define the buffer in, may be null * (buffer not created in workspace when null) */ public DataBuffer createBuffer(DataType dataType, long length, boolean initialize, MemoryWorkspace workspace) { // Implementation } ``` 3. **Handle nulls at the source** rather than requiring downstream methods to handle them, preventing defensive null checks throughout the codebase. 4. **Use appropriate types** for potentially null values from collections: ```java // Instead of: int numWords = (int) tokenizerConfig.get("num_words"); // Use: Integer numWords = (Integer) tokenizerConfig.get("num_words"); ``` 5. **Consider using annotations** like `@NonNull` or `@Nullable` to clearly indicate intent and enable static analysis tools to catch potential null issues. Following these practices helps prevent null pointer exceptions and makes code more robust and maintainable. --- ## Document all parameters Always provide complete and accurate documentation for all function parameters, especially when adding new ones. Each parameter should have a clear description that explains its purpose, expected values, and behavior. When adding a new parameter to an existing function: 1. Add documentation that clearly states what the parameter does 2. Explain any default behavior or special conditions 3. Use consistent formatting across similar functions For example, when adding a parameter like `failsafe`: ```cpp /** * \brief Allocation. * \param handle Handle struct. * \param failsafe Return a handle with a null dptr if out of memory, rather than exit. */ virtual void Alloc(Storage::Handle* handle, bool failsafe = false); ``` This helps other developers understand how to use the function correctly and makes the codebase more maintainable. Incomplete parameter documentation can lead to misuse of functions and introduces bugs that are difficult to diagnose. --- ## Thread-safe resource sharing When sharing mutable data between threads, use the `Arc>` pattern to ensure thread safety. `Arc` provides thread-safe reference counting for sharing ownership across thread boundaries, while `RwLock` enables controlled mutation of the shared data. This pattern is particularly important when: - Working across language boundaries (like Rust/Python bindings) - Sharing objects that might be accessed from different threads - Needing to mutate data that is referenced in multiple places ```rust // Instead of this (not thread-safe for mutation): let model = Arc::new(MyModel::new()); // Use this pattern for thread-safe mutation: let model = Arc::new(RwLock::new(MyModel::new())); // Reading from the shared resource: let data = model.read().unwrap().get_data(); // Writing to the shared resource: model.write().unwrap().update_data(); ``` When working with `RwLock`, `unwrap()` is generally acceptable for lock acquisition failures as they indicate a thread panic (unrecoverable state), but consider proper error handling in production code where appropriate. Remember that `RwLock` allows multiple simultaneous readers but only one writer, optimizing for read-heavy workloads. --- ## Use named constants In AI model implementations, avoid using magic numbers directly in code as they reduce readability and make maintenance difficult. Always define constants with meaningful names, especially for values related to tensor dimensions, indices, and type identifiers. For dimension limits: ```cpp // Instead of this: if (shape.ndim() >= 1 && shape.ndim() <= 12) { // Process shape } // Use this: const int MAX_ONEDNN_DIMS = 12; if (shape.ndim() >= 1 && shape.ndim() <= MAX_ONEDNN_DIMS) { // Process shape } ``` For array indices representing specific tensor components: ```cpp // Instead of this: if (n->inputs[2].node->is_variable()) { // Process bias } // Use this: const int BIAS_INDEX = 2; // Or better, use enum or named constant if (n->inputs[BIAS_INDEX].node->is_variable()) { // Process bias } ``` This practice makes code more maintainable as dimensions and tensor layouts evolve during AI model optimization efforts. --- ## Graph traversal optimization When working with graph structures, avoid performing redundant depth-first search (DFS) traversals as each traversal incurs an O(V+E) complexity cost. Instead, consider: 1. **Label nodes during initial traversal** to maintain state information for subsequent operations 2. **Cache traversal order** to avoid repeating the same path exploration 3. **Batch related operations** that can be performed in a single pass 4. **Create graph copies** when modifications might affect future traversals For example, instead of: ```cpp // Multiple independent DFS calls on the same graph structure for (auto pattern : patterns) { DFSVisit(sym.outputs, [&](const nnvm::ObjectPtr &node) { if (node->is_variable()) return; // Find nodes matching pattern }); } ``` Consider: ```cpp // Single traversal with collected state std::vector traversal_order; std::unordered_map node_labels; DFSVisit(sym.outputs, [&](const nnvm::ObjectPtr &node) { if (node->is_variable()) return; traversal_order.push_back(node); // Label nodes as needed }); // Now use cached traversal for pattern matching without repeating DFS for (auto pattern : patterns) { for (const auto& node : traversal_order) { // Match against patterns } } ``` This approach significantly reduces computational complexity when multiple operations or pattern matching need to be performed on the same graph structure. --- ## Simplify for readability Prioritize code readability by using simpler and more direct expressions. When possible, return values directly instead of using temporary variables and explicit return statements. Break complex logic into intermediate variables with descriptive names. Structure control flow for maximum clarity, preferring Rust idioms like match expressions over nested conditionals. Example 1 - direct returns: ```rust // Instead of: pub fn from_string(content: String) -> Result { let tokenizer = serde_json::from_str(&content)?; Ok(tokenizer) } // Prefer: pub fn from_string(content: &str) -> Result { serde_json::from_str(content) } ``` Example 2 - match expressions: ```rust // Instead of: if direction != "right" && direction != "left" { panic!("Invalid truncation direction value : {}", direction); } let tdir = if direction == "right" { TruncateDirection::Right } else { TruncateDirection::Left }; // Prefer: let direction = match direction.as_str() { "left" => Truncate::Left, "right" => Truncate::Right, other => panic!("Invalid truncation direction value : {}", other), }; ``` For complex code blocks, use intermediate variables with descriptive names to break down logic and make the code easier to follow. When implementing iterators or transformation functions, consider structuring them for readability even if it requires a few more lines of code. --- ## Consistent naming patterns Maintain consistent naming conventions throughout the codebase to enhance readability and reduce confusion. This applies to: 1. **Import aliases**: Use standardized aliases for imported libraries. When working with both MXNet's NumPy and the official NumPy, use 'onp' for the official NumPy to clearly distinguish between them: ```python import numpy as onp # Official NumPy from mxnet import np # MXNet NumPy ``` 2. **Parameter naming**: Use semantically appropriate parameter names that indicate their purpose. Avoid using 'self' outside of class methods, and prefer descriptive names like 'array' or 'x' for data parameters: ```python # Good def matrix_transpose(x: ndarray, /) -> ndarray: # implementation # Avoid def matrix_transpose(self: ndarray, /) -> ndarray: # implementation ``` 3. **Loop variables**: Use descriptive names for loop variables that represent what they iterate over: ```python # Good for key, value in data_shape.items(): # implementation # Avoid for obj in data_shape: # implementation ``` 4. **Type annotations**: Maintain a consistent style for type annotations throughout the codebase, with explicit type names for parameters and return values. 5. **Related variables**: Use consistent prefixes or suffixes for related variables (e.g., 'running_mean' and 'running_var' instead of mixing 'moving_' and 'running_' prefixes). --- ## Use explicit optional types When dealing with values that may be absent or null, always use explicit optional type wrappers instead of implicit null checks or nullable types without clear type constraints. This makes the code's intent clearer, prevents null reference errors, and improves type safety. In Perl, use `Maybe[Type]` to clearly indicate a value could be absent: ```perl has 'sum_metric' => (is => 'rw', isa => 'Maybe[Num|ArrayRef[Num]|PDL]'); ``` In C++, use appropriate optional containers like `dmlc::optional` (or `std::optional` in C++17) when a parameter might not have a value: ```cpp dmlc::optional shifted_output; // Clearly indicates this boolean might not be set ``` Be explicit about which values can be null and provide appropriate methods to safely access or transform these values. When working with optional types, ensure consistent handling across the codebase rather than using ad-hoc null checks. This pattern helps catch null-related errors at compile time rather than runtime. --- ## Manage configuration changes Carefully manage configuration file changes to ensure consistency and minimize unintended impacts across your project. When modifying configuration files: 1) Ensure compiler settings match runtime requirements - update targets to support required language features (like changing TypeScript target to "es2020" to support BigInt in Node.js 12) 2) Maintain consistent paths and settings across related configurations to prevent deployment issues ```json // Example: Consistent paths in build scripts "scripts": { "start": "ng serve --base-href /tensorboards/ --deploy-url /tensorboards/", "build": "ng build --prod --base-href /tensorboards/ --deploy-url static/" } ``` 3) Isolate high-impact configuration changes (like dependency updates that affect package-lock.json) into separate PRs to maintain reviewability and minimize unintended side effects --- ## Consistent API design When designing and modifying APIs, ensure consistency in parameter naming, default values, and which functionality is exposed. Each API design decision should: 1. Use parameter names that clearly communicate their purpose and behavior 2. Choose default values that align with expected behavior and maintain backward compatibility 3. Only expose methods and properties with justified use cases 4. Document parameter behavior thoroughly, especially when multiple interpretations are possible For example, when adding new parameters like in the `truncate` method: ```python def truncate(self, max_length, stride=0, left=True): """Truncate the sequence(s) represented by this encoding Args: max_length: The maximum length to truncate to stride: The length of the stride to use left: Whether to truncate left (True) or right (False) """ # implementation ``` Ensure the parameter name (`left`) clearly indicates what `True` and `False` values will do, and consider whether the default value matches users' expectations and existing behavior. Document any parameters that might have ambiguous interpretations to prevent confusion. --- ## Null-safe checks Make null/empty handling explicit and safe—so empty values don’t break logic or even generate invalid syntax, and raw null-pointer checks are replaced with semantic, invariant-based checks. Guidelines: 1) Avoid “empty variable” syntax bugs (CMake): quote variables in comparisons. - Bad: `elseif(${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang")` (breaks if the variable expands to empty) - Good: `elseif("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")` 2) Prefer semantic checks over raw pointer null checks (C++ containers/tensors): - Replace `if (ptr != NULL)` with `if (!obj.empty())` or equivalent invariants when available. - Example pattern: `if (!_bias.empty()) { /* use bias */ } else { /* no bias */ }` 3) Don’t over-defend against null in operations that are already null-safe: - `delete NULL;` is safe—unnecessary `if (ptr) delete ptr;` can be removed for clarity. 4) For null-terminated byte strings, ensure the correct terminator behavior: - When constructing/copying C-strings into custom buffers, allocate/copy consistently so the destination is properly null-terminated (e.g., consider whether you need `len + 1` and whether you copy `len+1`). Applying these rules reduces crashes, undefined behavior, and correctness issues caused by missing/empty/null values. --- ## Avoid redundant calculations Eliminate redundant calculations by identifying and caching frequently used values to improve performance. Consider these optimization patterns: 1. Cache function results when used multiple times: ```cpp // Before if (fabs(y) > 1.0) { ... } // later in the same function if (fabs(y) < CENTRAL_RANGE) { ... } // After double abs_y = fabs(y); if (abs_y > 1.0) { ... } // later if (abs_y < CENTRAL_RANGE) { ... } ``` 2. Move repeatedly calculated values to class attributes: ```cpp // Before - calculating strides in multiple methods void DNNLSplitFwd::Method1() { std::vector strides(ishape.ndim(), 1); for (int i = ishape.ndim() - 2; i >= 0; --i) { strides[i] = strides[i + 1] * ishape[i + 1]; } // use strides... } // After - calculate once and store in class class DNNLSplitFwd { std::vector strides; // Class member void CalculateStrides() { strides.resize(ishape.ndim(), 1); for (int i = ishape.ndim() - 2; i >= 0; --i) { strides[i] = strides[i + 1] * ishape[i + 1]; } } }; ``` 3. When working with containers, prefer `emplace_back` over `push_back` to avoid creating temporary objects: ```cpp // Before matched_list.push_back(&n); // After matched_list.emplace_back(&n); ``` These optimizations can significantly improve performance in computationally intensive applications by reducing unnecessary calculations, memory operations, and object constructions. --- ## Avoid unsafe code Prioritize memory safety and security over performance optimizations by avoiding unsafe code blocks, especially in libraries. Even when bounds are checked, unsafe code can introduce subtle security vulnerabilities and maintenance challenges. Prefer using safe Rust patterns and abstractions, even if it means a slight performance overhead (like an additional clone operation). Example: ```rust // Avoid this approach #[inline] fn split_off_back(vec: &mut Vec, at: usize) -> Vec { assert!(vec.len() >= at); let mut other = Vec::with_capacity(at); let left_over_len = vec.len() - at; let at_isize = at.try_into().unwrap(); unsafe { // unsafe implementation } } // Prefer this safer approach #[inline] fn split_off_back(vec: &mut Vec, at: usize) -> Vec { let other = vec[0..at].to_vec(); // Clone but safe vec.rotate_left(at); vec.truncate(vec.len() - at); other } ``` --- ## Document API completely All public APIs must have comprehensive and clear documentation that helps developers understand functionality without examining implementation details. Follow these guidelines: 1. **Methods and classes**: Document the purpose, behavior, parameters, and return values. Class-level documentation should explain usage patterns and limitations. ```java /** * Standardize input variable along given axis by subtracting mean and dividing by standard deviation. * * @param input The input variable to standardize * @param dimensions Dimensions along which to calculate statistics * @return Standardized variable with zero mean and unit variance along specified dimensions */ public SDVariable standardize(SDVariable input, int... dimensions) { // Implementation } ``` 2. **Empty or non-obvious implementations**: Always include comments explaining why a method is empty or has unexpected behavior. ```java @Override public void setValue(Number value) { // No action needed - this method intentionally left empty as value is managed by parent condition } ``` 3. **Deprecation**: Follow this format for all deprecated elements: - Add `@Deprecated` annotation - Include `@deprecated` Javadoc tag explaining why and what to use instead - Use `{@link}` references to replacements ```java /** * @deprecated As of version 1.0.0-beta, replaced by {@link #newMethod()} which provides better performance */ @Deprecated public void oldMethod() { // Implementation } ``` 4. **Method references**: Ensure `@see` and `{@link}` references are accurate and helpful. For overloaded methods, clearly specify which signature is being referenced and explain default behavior. ```java /** * As per {@link #pad(INDArray, int[][], List, PadMode)} with 'constantValues' being zeros (zero padding) */ public static INDArray pad(INDArray toPad, int[][] padWidth, PadMode padMode) { // Implementation } ``` 5. **Special elements**: Document enum values appropriately with Javadoc rather than inline comments. ```java public enum WeightsFormat { /** * Kernel height, kernel width, input channels, output channels [kH, kW, iC, oC] */ YXIO, /** * Output channels, input channels, kernel height, kernel width [oC, iC, kH, kW] */ OIYX } ``` --- ## Document environment variables All environment variables must be documented in the central env_var.md file with clear descriptions of their purpose, acceptable values, and effects. Use consistent naming patterns that reflect the subsystem they configure (e.g., MXNET_CUDNN_*, MXNET_MKLDNN_*) and avoid introducing new variables when existing ones can serve the same purpose. Example: ```cpp // Good - Uses consistent naming and is documented // In code: const bool brgemm_disabled = dmlc::GetEnv("MXNET_MKLDNN_DISABLE_BRGEMM_FC", true); // In docs/static_site/src/pages/api/faq/env_var.md: // MXNET_MKLDNN_DISABLE_BRGEMM_FC=[true|false] - Disable BRGEMM algorithm in fully connected layers when using MKLDNN backend. Default is true. // Bad - Introduces new variable without documentation static bool use_new_dep_engine = dmlc::GetEnv("MXNET_ASYNC_GPU_ENGINE", false); // Instead, reuse existing variable: // static bool use_new_dep_engine = (dmlc::GetEnv("MXNET_ENGINE_TYPE", "") == "AsyncGPU"); ``` When adding new configuration options: 1. Check if an existing variable can be extended instead of creating a new one 2. Follow the subsystem naming prefix pattern (MXNET_[SUBSYSTEM]_*) 3. Document the variable in env_var.md with its default value and purpose 4. For enum-like options, document all valid values and their effects --- ## Use pytest parameterization Structure unit tests using pytest's parameterize decorator instead of manual loops or wrapper functions. This approach improves test readability, makes failure cases easier to identify, and allows individual test cases to be run separately. When implementing tests with multiple inputs or configurations: 1. Replace manual iteration through test cases with `@pytest.mark.parametrize()` decorators 2. Use multiple parametrize decorators when testing combinations of parameters 3. Use pytest's built-in exception testing utilities for cleaner code Example refactoring: ```python # Before - manual iteration def test_operation(): test_cases = [ (5, 10, True), (3, 7, False), (0, 1, True) ] for a, b, expected in test_cases: result = operation(a, b) assert result == expected # After - pytest parameterization @pytest.mark.parametrize('a,b,expected', [ (5, 10, True), (3, 7, False), (0, 1, True) ]) def test_operation(a, b, expected): result = operation(a, b) assert result == expected ``` This approach makes tests more maintainable, documents test cases more clearly, and provides better reporting when tests fail by clearly identifying which specific parameter combination caused the failure. --- ## Centralize configuration parameters Avoid hardcoded paths and duplicated configuration values throughout the code. Instead: 1. Use dedicated configuration files for settings that appear in multiple places 2. Leverage environment variables for runtime path configurations 3. Implement runtime detection for system-specific paths when possible 4. When environment setup scripts are available (like `source /opt/intel/oneapi/setvars.sh`), prefer them over hardcoding paths Example of problematic code: ```bash # Hardcoded path that may not work across installations export CPATH=/opt/arm/armpl_21.0_gcc-8.2/include_lp64_mp:$CPATH # Duplicated test configuration pytest -m 'not serial' -k 'not test_operator' -n 4 --durations=50 --cov-report xml:tests_unittest.xml --verbose tests/python/unittest ``` Better approach: ```bash # Use environment detection or user configuration if [[ -d "${ARM_PATH}" ]]; then export CPATH=${ARM_PATH}/include_lp64_mp:$CPATH fi # Load configuration from a central file source ./test_config.sh pytest ${TEST_COMMON_ARGS} ${UNITTEST_ARGS} tests/python/unittest ``` This approach improves portability across different environments and makes maintenance easier when configurations need to change. --- ## Comprehensive API documentation Ensure all API elements are thoroughly documented following a consistent format. This includes: 1. **All function parameters** must have descriptive documentation that explains their purpose, expected values, and default behaviors. 2. **Follow established documentation formats** for consistency across the codebase. Reference existing well-documented functions as templates. 3. **Document relationships between APIs** by clearly indicating when functions are aliases or standardized versions of other APIs, including appropriate references. 4. **Include practical examples** in documentation to demonstrate usage patterns. Example of proper parameter documentation: ```python parser.add_argument('--batch_size', type=int, default=64, help='Number of samples per training batch') parser.add_argument('--learning_rate', type=float, default=0.001, help='Initial learning rate for training') ``` Example of documenting API relationships: ```python atan = arctan atan.__doc__ = """ Trigonometric inverse tangent, element-wise. The inverse of tan, so that if ``y = tan(x)`` then ``x = atan(y)``. Notes --------- `atan` is a standard API in the Array API Standard (https://data-apis.org/array-api/latest/API_specification/elementwise_functions.html#atan-x) and is equivalent to `arctan`. >>>np.atan is np.arctan True Parameters ---------- # parameter documentation follows... """ ``` --- ## Document API completely Always provide comprehensive API documentation that clearly specifies: 1. **Parameter types** - Document all acceptable parameter types, not just specific implementations. When a parameter accepts any object that satisfies certain behavior (like iterables), explicitly state this rather than referencing a specific class. 2. **Function aliases** - When implementing function aliases (like `acos` for `arccos` or `pow` for `power`), clearly document their relationship to the original function and explain why the alias exists. 3. **Standards compliance** - Reference any industry standards or specifications that the API follows, especially when they might differ from what users expect. Example: ```python def process_data(data_source, options=None): """Process data from the provided source. Parameters ---------- data_source : iterable object Any iterable that yields data batches. This can be a DataLoader instance, a list of arrays, or any custom iterable implementing the required interface. options : dict, optional Processing options. Notes ----- This function follows the data processing standards specified in https://example.org/standards/data-processing. """ ``` Or when documenting aliases: ```python acos = arccos acos.__doc__ = """ Trigonometric inverse cosine, element-wise. Notes ---------- `acos` is an alias for `arccos`. It is a standard API in https://data-apis.org/array-api/latest/ instead of an official NumPy operator. >>> np.acos is np.arccos True """ ``` --- ## Eliminate redundant constructs Remove unnecessary coding patterns that add complexity without providing value. Focus on clarity and simplicity by: 1. Not using enumerate() when the index is unused: ```python # Instead of: for _, item in enumerate(collection): process(item) # Use: for item in collection: process(item) ``` 2. Using generator expressions instead of list comprehensions when creating iterables directly: ```python # Instead of: return tuple([x.astype(dtype) for x in args]) # Use: return tuple(x.astype(dtype) for x in args) ``` 3. Following Python's idiomatic expressions for boolean operations: ```python # Instead of: if (upper == False): do_something() # Use: if not upper: do_something() ``` These simplifications improve code readability and maintain a clean, Pythonic style that aligns with best practices. --- ## Optimize validation checks When implementing validation and requirement checks, balance thoroughness with performance considerations. Critical validations should remain unconditional, but optimize their implementation to minimize performance impact: 1. Use short-circuit evaluation with logical operators (&&) to avoid unnecessary validations 2. Implement lazy evaluation for complex checks using lambdas 3. Consider conditionally enabling detailed error reporting in debug mode only 4. Pay special attention to validation code in performance-sensitive paths ```cpp // Good practice - using short-circuit and lazy evaluation Requirements req("CUDNN OPERATION"); req.expectIn(makeInfoVariable(dataType, TYPE_MSG), {ValidTypes}) && req.expectTrue([&]() { // Complex validation only evaluated if previous check passes return validateComplexCondition(input); }); // Avoid unconditional evaluation of everything, especially in hot paths // auto info = getDetailedInfo(input); // Always executed regardless of need // if (!meetsRequirements(info)) return false; ``` This approach ensures your code remains robust with meaningful error reporting while minimizing performance overhead in production environments. --- ## Hybridization compatible operations When implementing neural network models that will be hybridized for performance optimization, use operations that are compatible with symbolic execution to avoid runtime errors. Hybridization converts imperative code to symbolic for better inference performance, but requires special handling of certain operations. Key practices: 1. Replace index operators with slice operations (e.g., use F.slice() instead of [:, :, -x:]) 2. Avoid direct references to shape attributes; calculate dimensions explicitly 3. Handle parameter fusion appropriately, especially in RNN layers 4. Test both hybridized and non-hybridized execution paths using parameterized tests Example of refactoring code for hybridization compatibility: ```python # NOT compatible with hybridization def forward(self, x): skip_connections = [...] output = sum([s[:, :, -output.shape[2]:] for s in skip_connections]) return output # Compatible with hybridization def forward(self, x): skip_connections = [...] # Option 1: Use F.slice with calculated dimensions slice_size = calculate_slice_size(...) # Calculate based on input size and model params output = sum([F.slice(s, begin=(0, 0, -slice_size), end=(None, None, None)) for s in skip_connections]) return output ``` When implementing features like callbacks with hybridization, be aware of limitations with static shapes and mark experimental features appropriately in documentation. --- ## Centralize synchronization logic When implementing concurrent operations, especially in heterogeneous computing environments (CPU/GPU), centralize synchronization management in dedicated components rather than using flags scattered throughout the codebase. This approach improves maintainability, reduces the potential for race conditions, and makes concurrency behavior more predictable. For example, instead of using flags like: ```cpp struct RunContext { // Other context data... bool is_bulk; // Flag to indicate if synchronization is needed }; // Usage in various places if (!context.is_bulk) { // Perform synchronization } ``` Prefer a centralized approach where synchronization is managed by a specialized component: ```cpp struct RunContext { // Other context data... void *event_pool = nullptr; // Pointer to centralized event management }; // Centralized synchronization management void SynchronizeOperations(RunContext* ctx) { // Handle all synchronization based on events from event_pool } ``` This pattern is particularly important for CUDA operations where proper event ordering and stream synchronization are critical for correctness. Using centralized event pools and dependency tracking helps ensure operations complete in the correct order without unnecessary synchronization points. --- ## Optimize iteration patterns When iterating through collections, choose the most efficient iteration pattern based on what information you actually need. If you only need the elements without using their indices, use direct iteration instead of enumerate: ```python # Instead of this (inefficient): for _, item in enumerate(collection): process(item) # Do this (efficient and clearer): for item in collection: process(item) ``` This optimization removes unnecessary index variable allocation and makes the code more readable. The principle applies to any iterative algorithm - don't compute values you won't use. Similarly, when testing object capabilities (like whether an object is iterable), check for specific attributes (`hasattr(obj, '__iter__')`) rather than calling functions that might have side effects like prefetching data. --- ## Consistent API documentation Maintain high-quality, consistent documentation as a critical component of API design. Documentation should feature: 1. Correct grammar and spelling, including proper punctuation and sentence structure 2. Consistent terminology throughout, especially for parameter names and technical terms 3. Clear explanations of parameter usage and behavior differences Example: ```python # GOOD: Clear, consistent documentation with proper terminology """ Returns a uniform distribution array. Parameters: ---------- low : float, optional Lower boundary of the output interval. Default is 0. high : float, optional Upper boundary of the output interval. Default is 1. size : tuple, optional Output shape. Default is None. """ # BAD: Inconsistent terminology and grammatical errors """ Returns uniform distribution array. Parameters: ---------- low : float, optional lower boundary of output interval. Default is 0 high : float, optional upper boundary of the output interval. Default is 1 shape : tuple, optional Output size. Default is None. """ ``` Consistent documentation reduces developer confusion and improves API adoption. It serves as the primary interface between your API and its users, making it as important as the implementation itself. --- ## Configurable resource locations Always make file paths, temporary directories, and resource locations configurable with reasonable defaults instead of hard-coding them. Users may have specific environment requirements such as using SSDs instead of system drives or working with constrained environments like Spring Boot. Implement a hierarchical approach to resource configuration: 1. Allow explicit configuration through system properties or configuration files 2. Provide fallback to environment-specific defaults when explicit configuration isn't available 3. Document all configurable paths and their default values For example, instead of: ```java File holder = File.createTempFile("FileChunksTracker", "Message"); ``` Use a configurable approach: ```java // Define in a centralized properties class public static final String FILE_STORAGE_DIR_PROPERTY = "org.nd4j.tempfiles.directory"; // Use in implementation String tempDir = System.getProperty(FILE_STORAGE_DIR_PROPERTY, System.getProperty("java.io.tmpdir")); File storageDir = new File(tempDir); if (!storageDir.exists()) { storageDir.mkdirs(); } File holder = File.createTempFile("FileChunksTracker", "Message", storageDir); ``` This practice improves flexibility across different deployment environments and facilitates troubleshooting when resource loading issues occur. --- ## Validate inputs explicitly Always validate input parameters and respond with appropriate HTTP status codes when invalid values are detected, even when inputs appear controlled by your frontend. Backend validation should explicitly check for invalid or unexpected values (like "NaN" or values outside an allowed set) and raise appropriate exceptions with clear error messages. Example: ```python def set_server_type(notebook, body, defaults): notebook_annotations = notebook["metadata"]["annotations"] server_type = get_form_value(body, defaults, "serverType") # Validate server type is one of the allowed values allowed_types = ["jupyter", "rstudio", "vscode", None] if server_type not in allowed_types: raise werkzeug.exceptions.BadRequest( f"Invalid server type: {server_type}. Must be one of: {allowed_types}") notebook_annotations["notebooks.kubeflow.org/server-type"] = server_type ``` This practice ensures your API is robust against malformed inputs regardless of their source, provides clear error messages for debugging, and maintains a clean separation of concerns between frontend and backend validation. --- ## Mark UI text i18n {% raw %} All user-facing text in HTML templates should be marked for internationalization using the i18n directive. This includes labels, placeholders, error messages, and any other text displayed to users. Using the i18n directive ensures the text can be properly extracted for translation and maintains consistent internationalization throughout the application. Example: ```html {{ 'common.name' | translate }} Name ``` Note that for attributes like placeholders, use the i18n-attribute syntax (e.g., i18n-placeholder) to mark them for translation. {% endraw %} --- ## Preserve API compatibility When evolving APIs, prioritize backward compatibility to protect existing client code. Make new parameters optional whenever possible to allow existing code to continue functioning. If breaking changes are necessary, evaluate how users typically interact with your API before proceeding. Example: ```kotlin // Good: Adding a new parameter with a default value val reduce = Mixin("reduce"){ Input(DataType.NUMERIC, "in") { description = "Input variable" } // New parameter with default value maintains compatibility Arg(DataType.BOOL, "keepDims", default = false) { "Whether to keep original dimensions or produce a shrunk array" } Arg(DataType.INT, "dimensions") { /* ... */ } } // Consider impact: Breaking changes may be acceptable if most users // are protected by higher-level abstractions (e.g., factory methods) // rather than using these classes directly ``` Breaking changes may be acceptable when most users access functionality through higher-level abstractions (like factory methods) that can shield them from underlying implementation changes. Always document breaking changes clearly in release notes. --- ## Document for comprehension Add comprehensive documentation that helps others understand both the interface and implementation of your code. This includes: 1. **Detailed parameter documentation** in docstrings with type information and purpose descriptions, especially for new or non-obvious parameters 2. **Explanatory comments** for complex logic, algorithms, or when integrating external libraries 3. **Clear examples** when appropriate to demonstrate usage Example of good parameter documentation: ```python def train( files: List[str], vocab_size: int = 8000, show_progress: bool = True, unk_token: Optional[str] = None, ): """ Train the model using the given files Args: files (:obj:`List[str]`): A list of path to the files that we should use for training vocab_size (:obj:`int`): The size of the final vocabulary, including all tokens and alphabet. show_progress (:obj:`bool`): Whether to show progress bars while training. unk_token (:obj:`str`, `optional`): The unknown token to be used by the model. """ ``` Example of good implementation comments: ```python class JiebaPreTokenizer: def jieba_split(self, pretoken_index, pretoken): new_tokens = [] # Convert to string to ensure compatibility with jieba tokenizer pretoken_string = str(pretoken) # Extract tokens using jieba's tokenize function which returns (word, start, end) for token, start, stop in jieba.tokenize(pretoken_string): new_tokens.append(pretoken[start:stop]) return new_tokens def pre_tokenize(self, pretok): # Split the PreTokenizedString using our custom jieba_split function # which handles tokenization based on Chinese word boundaries pretok.split(self.jieba_split) ``` --- ## Use logging best practices Adopt these logging best practices to ensure consistent, efficient, and meaningful logs: 1. **Use Lombok's `@Slf4j` annotation** instead of manually declaring loggers: ```java // Avoid this: private static final Logger log = LoggerFactory.getLogger(YourClass.class); // Prefer this: @Slf4j public class YourClass { // Logger field 'log' is automatically created } ``` 2. **Choose appropriate log levels** based on the information's importance: - `log.trace()`: Very detailed information, typically only valuable when debugging specific issues - `log.debug()`: Development-time information like "Stringing exec...", "exec done." - `log.info()`: Production-worthy information about application progress - `log.warn()`: Potential issues that don't prevent operation - `log.error()`: Actual failures requiring attention 3. **Log exceptions properly** by passing the exception object as an argument: ```java // Avoid this: try { // code } catch (Exception e) { log.error("Operation failed."); e.printStackTrace(); // Redundant and can go to a different output stream } // Prefer this: try { // code } catch (Exception e) { log.error("Operation failed.", e); // Includes stack trace automatically } ``` Following these practices makes logs more consistent, easier to search, and more valuable for debugging. --- ## Clear descriptive identifiers Choose clear, self-descriptive names for all code identifiers that accurately reflect their purpose and behavior. Method names should be verbs or verb phrases that indicate their function without ambiguity. For boolean methods, use prefixes like "is", "has", or "should" followed by the condition they check. When generating identifiers programmatically, use distinctive prefixes to avoid potential collisions with user-defined names. For example, prefer domain-specific prefixes like `sd_var_` over generic ones like `var_` to reduce collision risk. ```java // Avoid: public final static boolean gilIsReleaseAutomatically() {} // awkward phrasing, hard to parse private void parseSetupAndExecCode() {} // ambiguous, could mean "parse setup and execute code" String varName = "var_" + _var_id.toString(); // too generic prefix // Prefer: public final static boolean releaseGilAutomatically() {} // direct and clear private void parseSetupAndExecutionCode() {} // clearer alternative // or better with JavaDoc explaining the purpose /** * Parses both the setup code and execution code sections from the configuration. */ private void parseCodeSections() {} String varName = "sd_var_" + String.valueOf(_var_id); // domain-specific prefix ``` Meaningful naming reduces the need for comments, improves code readability, and makes the codebase more maintainable for all developers. --- ## Cross-platform algorithm optimization When implementing algorithms that need to execute efficiently across different platforms, consider both compile-time and runtime optimizations: 1. For template-heavy code, use explicit instantiations to improve compilation speed and avoid compiler limitations on specific platforms: ```cpp // Use CMake to generate explicit template instantiations // in separate compilation units #cmakedefine LIBND4J_TYPE_GEN #include ``` 2. Use platform-agnostic type definitions to ensure consistent behavior, particularly when interfacing between languages like C++ and Java: ```cpp // Prefer explicit sized types rather than platform-dependent types typedef int Nd4jInt; // For 32-bit integers typedef long long Nd4jLong; // For 64-bit integers ``` 3. Avoid calling member functions from constructors when inlining might be deactivated: ```cpp // Instead of: // if (rootSeed == 0) // rootSeed = currentMilliseconds(); // Directly use the implementation: if (rootSeed == 0){ auto s = std::chrono::system_clock::now().time_since_epoch(); rootSeed = std::chrono::duration_cast(s).count(); } ``` 4. When working with hardware acceleration libraries like CUDA, create wrapper classes that handle version differences and provide consistent error handling: ```cpp template FORCEINLINE void callCudnnIfNoErr(cudnnStatus_t &err, Op op, Args&&... args) { if(err==CUDNN_STATUS_SUCCESS) { err = op(std::forward(args)...); if(err) { nd4j_printf("Cudnn error code %s\n", cudnnGetErrorString(err)); } } } ``` Always document platform-specific considerations directly in the code to help future developers understand your optimization decisions. --- ## Document in-code decisions Always include explanations for implementation decisions, non-obvious constructs, and specialized functions directly within the code as comments, rather than relying on external systems like commit messages or GitHub discussions. This practice ensures that future developers can understand the code's purpose and behavior without having to search through external documentation. For example, when using specialized functions or constructs like in this case: ```cpp // This prepares data for GPU processing by synchronizing host memory to device memory // and ensures proper buffer handling before computation NDArray::prepareSpecialUse({ &output }, { &input }); // Implementation code... // This synchronizes results back from device memory to host memory NDArray::registerSpecialUse({ &output }, { &input }); ``` Similarly, when implementing workarounds or choosing specific implementations: ```cpp // We default to our custom implementation here because cuDNN has precision issues // with non-standard padding values and dilated convolutions return goodType && (input->dataType() == gradO->dataType()); ``` This approach makes code more maintainable and reduces onboarding time for new team members who may not have access to historical commit messages or discussions. --- ## Use modern JavaScript idioms Favor modern JavaScript syntax and clean code practices to improve readability and maintainability. This includes: 1. **Use template literals** instead of string concatenation for clearer string interpolation: ```javascript // Preferred window.open(`/${namespace}/${notebook}`, "_blank"); // Avoid window.open("/" + namespace + "/" + notebook, "_blank"); ``` 2. **Apply object destructuring** to reduce repetition and improve readability: ```javascript // Preferred const {contentDocument} = iframe; contentDocument.addEventListener('click', handleEvent); // Avoid iframe.contentDocument.addEventListener('click', handleEvent); ``` 3. **Flatten nested conditionals** when possible to reduce complexity: ```javascript // Preferred if (!queryParams || !queryParams["ns"]) { return this.buildHref(href, this.queryParams); } return this.buildHref(href.replace('{ns}', queryParams["ns"]), queryParams); // Avoid if (queryParams) { if (queryParams["ns"]) { if (queryParams["ns"] !== null) { // ... } } } ``` 4. **Remove unused code** including imports, commented-out code, and debug logging statements: ```javascript // Remove before committing console.log({own: (owned||[]).namespace, namespaces, ns: this.selected}); ``` Maintaining these practices will lead to more consistent, readable, and maintainable code across the codebase. --- ## Modular adaptive configurations Structure configuration scripts with modularity and adaptability in mind. Extract repeated parameters into variables, separate parameter construction from command execution, and use dynamic detection for environment-specific values instead of hardcoding them. This approach improves readability, maintainability, and resilience to changes in the environment. Example: ```bash # Instead of repeating parameters in each condition: if [ "${HELPER}" != '' ] && [ "${EXTENSION}" != '' ]; then command="mvn -Possrh -Djavacpp.platform.extension=-${HELPER}-${EXTENSION} ... -DskipTests" elif [ "${HELPER}" != '' ]; then command="mvn -Possrh -Djavacpp.platform.extension=-${HELPER} ... -DskipTests" else command="mvn -Possrh -Djavacpp.platform.extension=${EXTENSION} ... -DskipTests" fi # Prefer modular construction: common_params="-Possrh -Dlibnd4j.buildThreads=${buildThreads} -Djavacpp.platform=linux-x86_64 -Dlibnd4j.chip=cuda --also-make -Pcuda clean --batch-mode package deploy -DskipTests" if [ "${HELPER}" != '' ] && [ "${EXTENSION}" != '' ]; then mvn_ext="-Djavacpp.platform.extension=-${HELPER}-${EXTENSION} -Dlibnd4j.helper=${HELPER} -Dlibnd4j.extension=${EXTENSION}" elif [ "${HELPER}" != '' ]; then mvn_ext="-Djavacpp.platform.extension=-${HELPER} -Dlibnd4j.helper=${HELPER}" else mvn_ext="-Djavacpp.platform.extension=${EXTENSION}" fi command="mvn ${common_params} ${mvn_ext}" # Use dynamic version detection instead of hardcoding: # Instead of: sudo cp /usr/lib/gcc/x86_64-linux-gnu/5.5.0/libgomp.so /usr/lib gcc_version=$(gcc --version | head -n 1 | grep -o '[^ ]*$') sudo cp /usr/lib/gcc/x86_64-linux-gnu/${gcc_version}/libgomp.so /usr/lib ``` --- ## Document networking annotations When using Istio or other networking-related annotations in configuration files, always include detailed comments explaining their purpose, behavior, and effects. This makes networking constraints and logic transparent to developers and users who need to understand the system's behavior. For each networking annotation: 1. Document what the annotation does 2. Explain when/why it's applied 3. Note any specific paths or headers affected Example: ```yaml imageGroupOne: # The annotation `notebooks.kubeflow.org/http-rewrite-uri: /` # is applied to notebook in this group, configuring # the Istio rewrite for containers that host their web UI at `/` value: public.ecr.aws/j1r0q0g6/notebooks/notebook-servers/codeserver-python:master-1831e436 imageGroupTwo: # The annotation `notebooks.kubeflow.org/http-rewrite-uri: /` # is applied to notebook in this group, configuring # the Istio rewrite for containers that host their web UI at `/` # The annotation `notebooks.kubeflow.org/http-headers-request-set` # is applied to notebook in this group, configuring Istio # to add the `X-RStudio-Root-Path` header to requests value: public.ecr.aws/j1r0q0g6/notebooks/notebook-servers/rstudio:master-1831e436 ``` This practice ensures that network routing behaviors are explicit, making the system more maintainable and reducing confusion when debugging networking issues. --- ## Stable Benchmarking Practices When collecting performance numbers, ensure both (1) benchmark parameters match the target hardware and (2) the execution environment is stable/isolated—otherwise results can be misleading. Apply this: - Use hardware-appropriate CPU threading: don’t oversubscribe a small CPU with too many threads. - For accelerator/GPU runs, reduce sources of contention by using a conservative CPU thread count (e.g., single-thread or a value aligned to physical cores) and keep the GPU as uncontended as possible. - If results are unstable across runs, treat it as a performance “bug” in your test setup: check whether other processes are using the GPU, stop/avoid them, and retest until the output stabilizes before updating documentation. Example (command-line style): - CPU thread sizing: - Prefer something aligned to the machine, e.g. `./benchncnn 1 ...` or `./benchncnn 8 ...` for an 8-core CPU, rather than a larger thread count. - Retest after isolating the GPU: - If you suspect other GPU activity, rerun the exact same command after eliminating contention, then record only the stable run results. --- ## Load configurations efficiently When designing components that require configuration, follow these practices to enhance performance, maintainability, and usability: 1. **Load configuration once at startup** rather than repeatedly during reconciliation loops: ```go // Good: Load at controller initialization func NewMyController() *MyController { // Load config once when controller starts config, err := loadConfigFromFile(configPath) if err != nil { // Handle error or fail fast } return &MyController{config: config} } // Avoid: Loading in reconcile loop func (r *MyController) Reconcile() { // Don't do this - performance issue config, _ := loadConfigFromFile(configPath) // ... } ``` 2. **Use standard formats** (YAML/JSON) with established libraries instead of creating custom parsers: ```go // Good: Use standard libraries import "github.com/go-yaml/yaml" func loadConfig(file string) (Config, error) { var config Config data, err := os.ReadFile(file) if err != nil { return config, err } return config, yaml.Unmarshal(data, &config) } // Avoid: Custom parsing logic func parseConfig(file string) { scanner := bufio.NewScanner(file) for scanner.Scan() { line := scanner.Text() // Custom parsing logic is harder to maintain } } ``` 3. **Don't hardcode configuration paths** - provide reasonable defaults but allow overriding via command line arguments: ```go // Good: Make path configurable var configPath = flag.String("config", "/etc/default/config.yaml", "Path to configuration file") func main() { flag.Parse() config, err := loadConfig(*configPath) // ... } ``` 4. **Set sensible defaults** for configuration values but provide clear ways to override them through explicit configuration. These practices help avoid reinventing parsing logic, improve performance by reducing unnecessary I/O operations, and make your components more configurable across different environments. --- ## Standardize build configurations All components should use consistent build configurations and patterns in their CI/CD setup. This includes standardizing Makefile variables, build commands, and docker build processes across repositories. Inconsistent build configurations make CI/CD pipelines difficult to maintain and can lead to confusion during development. For example, use consistent variable naming across Makefiles: ```bash # Use consistent variable names like REGISTRY_PROJECT REGISTRY_PROJECT=my-repo make docker-build ``` Instead of having different variable names for the same concept in different components as noted in the discussion: "Tensorboard's makefile uses slightly different vars but we should iron them out and have the same template" This standardization simplifies CI/CD pipeline maintenance, improves developer experience when working across components, and ensures that all artifacts follow the same build and testing patterns. It also makes it clearer which components are part of the official CI/CD pipeline and which are provided as examples only. --- ## Use CSS classes properly Avoid inline styles and `!important` declarations in your HTML templates. Instead, define and use CSS classes that encapsulate styling needs. This improves code maintainability, readability, and reduces CSS specificity issues. Bad example: ```html ``` Good example: ```html .server-type { height: 32px; width: 150px; } .server-type-wrapper { margin-bottom: 1rem; } ``` This approach makes your styles more maintainable, easier to debug, and allows for better responsiveness. CSS classes can be reused across components and modified centrally rather than hunting through templates for inline styles. --- ## Follow API conventions When designing APIs, adhere to established API conventions, particularly Kubernetes API conventions when working within the Kubernetes ecosystem. This improves API clarity, maintainability, and future compatibility. Key practices: 1. **Use standard data formats** instead of custom parsing methods ```go // Instead of custom string parsing: requestHeaders := strings.Split(annotations["notebooks.kubeflow.org/http-headers-request-set"], "\n") // Prefer using standard JSON: var requestHeaders map[string]string if err := json.Unmarshal([]byte(annotations["notebooks.kubeflow.org/http-headers-request-set"]), &requestHeaders); err != nil { // Handle error } ``` 2. **Use explicit field definitions** rather than embedding complex objects ```go // Instead of embedding the entire ObjectMeta: type PodDefaultSpec struct { // ObjectMeta defines the metadata to inject into the pod metav1.ObjectMeta `json:"metadata,omitempty"` } // Be specific about which fields you need: type PodDefaultSpec struct { // Labels to inject into pod metadata Labels map[string]string `json:"labels,omitempty"` // Annotations to inject into pod metadata Annotations map[string]string `json:"annotations,omitempty"` } ``` 3. **Use conditions instead of enums** for representing status ```go // Instead of enum-style status: type ProfileState string // Use standard Kubernetes condition pattern: type ProfileCondition struct { Type string `json:"type"` Status v1.ConditionStatus `json:"status"` LastUpdateTime metav1.Time `json:"lastUpdateTime,omitempty"` LastTransitionTime metav1.Time `json:"lastTransitionTime,omitempty"` Reason string `json:"reason,omitempty"` Message string `json:"message,omitempty"` } ``` Following these conventions enhances API clarity, avoids reinventing the wheel, and ensures your APIs evolve gracefully as requirements change. --- ## Unique workflow step names When defining CI/CD workflows, always ensure task/step names are unique to prevent execution failures. Workflow engines like Argo will reject pipelines with duplicate step names, which becomes particularly important when: 1. Building multiple similar artifacts 2. Generating steps programmatically 3. Reusing step templates To ensure uniqueness, append identifiers like random strings, build numbers, or artifact identifiers to your step names. Example: ```python # Import required libraries import random import string # Define character set for random string generation alphabet = string.ascii_lowercase + string.digits # Create unique step name by appending a random string task["name"] = "base-task-name-" + ''.join(random.choices(alphabet, k=8)) ``` This approach ensures each workflow step has a unique identifier while maintaining readability with a consistent prefix, allowing for reliable execution and easier debugging of CI/CD pipelines. --- ## Control header modification When allowing user-configurable HTTP headers in your application, implement strict validation to prevent security bypasses. Users should never be allowed to override security-critical headers that could compromise authentication or authorization mechanisms. Use a whitelist approach for maximum security: ```go // Example: Whitelist approach for header validation if _, ok := annotations["app.kubeflow.org/http-headers-request-set"]; ok { requestHeaders := strings.Split(annotations["app.kubeflow.org/http-headers-request-set"], "\n") for _, kv := range requestHeaders { if len(strings.Split(kv, ": ")) == 2 { k := strings.Split(kv, ": ")[0] v := strings.Split(kv, ": ")[1] // Only allow non-standard headers with X- prefix if strings.HasPrefix(k, "X-") { // Further validate against sensitive headers if !isRestrictedHeader(k) { headers["request"].(map[string]interface{})["set"].(map[string]interface{})[k] = v } } } } } ``` This prevents attackers from overriding critical headers like authentication tokens (e.g., `userid-header`), protocol information (e.g., `X-Forwarded-Proto`), or other security mechanisms. For applications with specific header requirements, maintain a carefully curated whitelist rather than allowing arbitrary header manipulation. --- ## Numerical stability practices When implementing machine learning algorithms, ensure numerical correctness and stability by following these practices: 1. Use appropriate default parameters based on research paper recommendations. For example, in AdaBelief, use smaller epsilon values as recommended by the authors: ```java // Instead of this public static final double DEFAULT_EPSILON = 1e-8; // Use this public static final double DEFAULT_EPSILON = 1e-14; // Follows paper recommendation ``` 2. Add validation for parameter ranges, especially probability values: ```java // Add checks like this for masking probabilities Preconditions.checkArgument(maskProb > 0 && maskProb < 1, "Probability must be between 0 and 1, got %s", maskProb); Preconditions.checkArgument(maskTokenProb + randomTokenProb <= 1.0, "Sum of probabilities must be <= 1, got %s", maskTokenProb + randomTokenProb); ``` 3. Include small epsilon values in calculations that could produce numerical instability: ```java // When performing normalization or similar operations SDVariable scale = SD.math.sqrt(squaredNorm.plus(1e-5)); // Prevents underflow ``` 4. Use proper variable references rather than hardcoded names to ensure calculations are handled correctly: ```java // Instead of this return sd.math.abs(labels.sub(sd.getVariable("out"))).mean(1); // Use this return sd.math.abs(labels.sub(layerInput)).mean(1); ``` These practices help prevent subtle numerical bugs that can affect model convergence, training stability, and inference quality. They're especially important in deep learning where calculations involve many operations that could compound numerical errors. --- ## Consistent separator conventions Use appropriate separators in compound identifiers to improve readability and ensure naming consistency across the codebase. Specifically: 1. Use hyphens to separate words in multi-word paths, repository names, and other resources: - Correct: `wg-deployment`, `feature-name` - Incorrect: `wgdeployment`, `featurename` 2. For version references, use the "vX.Y" format consistently: - Correct: `v1.0`, `v2.3` - Avoid: `0.Y`, `1.0` (without v prefix) This practice makes identifiers more readable, maintains consistency with standard conventions, and helps ensure references remain valid over time as the codebase evolves. Consistent naming patterns reduce the need for future refactoring and make documentation more predictable and easier to navigate. --- ## Configurable security with defaults Make security features configurable through environment variables or configuration files, but always implement secure defaults. This allows teams to adapt security controls to their specific deployment environments while maintaining a secure baseline. When implementing configurable security features: 1. Use secure default values that prioritize security (e.g., "Strict" for SameSite cookies) 2. Validate input configurations and fallback to secure defaults when invalid 3. Document all security configurations and their implications Example from CSRF implementation: ```python # Read SameSite configuration from environment with secure default samesite = os.environ.get("CSRF_SAMESITE", "Strict") # Validate the input to ensure only secure options are accepted if samesite not in ["Strict", "Lax", "None"]: samesite = "Strict" # Fallback to secure default # Apply the configuration to the cookie response.set_cookie( "CSRF_COOKIE", csrf_token, httponly=True, secure=True, samesite=samesite ) ``` Document this configuration in your README: ```markdown ## Environment Variables | Variable | Description | Default | |----------|-------------|---------| | CSRF_SAMESITE | SameSite attribute for CSRF cookies (Strict, Lax, None) | Strict | ``` This approach balances security with flexibility, allowing secure operation in various environments while maintaining strong defaults. --- ## Validate by File Header When parsing untrusted files (e.g., images), do not choose decode/encode logic based on filename suffix/substring (e.g., “.pgm/.ppm/.jpg”). Instead, detect the actual format using file content (magic bytes/header) and only proceed if it matches supported signatures; otherwise fail safely. Why: filename-based routing is trivially bypassed/ambiguous (e.g., “lena.jpg.png”); it can send data down the wrong parser path. Apply it like this (minimal pattern): ```cpp // Read first bytes, then decide format by magic/header. // Do not rely on path.find(...) or last-N extension checks. enum class ImgFmt { PGM, PPM, JPG, Unknown }; ImgFmt sniff_fmt(FILE* fp) { unsigned char b[8] = {0}; size_t n = fread(b, 1, sizeof(b), fp); fseek(fp, 0, SEEK_SET); // PGM/PPM: start with ASCII 'P' then '5' (binary PGM) or '6' (binary PPM) if (n >= 2 && b[0] == 'P' && (b[1] == '5' || b[1] == '6')) return b[1] == '5' ? ImgFmt::PGM : ImgFmt::PPM; // Example JPG SOI if (n >= 2 && b[0] == 0xFF && b[1] == 0xD8) return ImgFmt::JPG; return ImgFmt::Unknown; } cv::Mat imread_secure(const std::string& path) { FILE* fp = fopen(path.c_str(), "rb"); if (!fp) return cv::Mat(); ImgFmt fmt = sniff_fmt(fp); if (fmt == ImgFmt::Unknown) { fclose(fp); return cv::Mat(); } // Decode based on fmt (not on filename suffix), with strict size/bounds checks. // ... fclose(fp); return cv::Mat(); } ``` Team standard: - Prefer magic-byte/header sniffing over extension checks. - If the header doesn’t match the expected decoder, return an error/empty result. - Keep fallback logic conservative; never let extension-based routing be the sole authority for untrusted inputs. --- ## Pythonic API design Design APIs that follow Python language conventions and idioms rather than blindly mirroring the underlying implementation language. Consider what would feel most natural to Python developers in terms of parameter ordering, default values, and call patterns. Key principles: - Place frequently used parameters first, with optional parameters later using default values - Use named arguments for optional parameters rather than positional ones - Consider the readability and usability of parameter signatures from the Python developer's perspective - Create convenient interfaces that hide complex internal data structures while preserving functionality Example: ```python # Instead of exposing complex implementation details: def initialize( vocab: Optional[Union[str, Dict[str, int]]] = None, merges: Optional[Union[str, Dict[Tuple[int, int], Tuple[int, int]]]] = None, ) # Provide a more Pythonic interface: def initialize( files, vocab_size=30000, min_frequency=2, special_tokens=None ) ``` When adapting APIs from other languages, prioritize what makes sense for Python users rather than strictly adhering to the source language patterns. This improves usability while reducing the learning curve for your library. --- ## Document API stability When working with AI frameworks and machine learning libraries, clearly document the stability state of APIs being used. For experimental or evolving features: 1. Add explicit warnings about API stability in documentation 2. Provide workarounds for unstable features while indicating when they might be resolved 3. Link to official documentation rather than source code when possible For example, when documenting a feature with known limitations: ```swift // EXPERIMENTAL: Boolean operators (&&, ||) are not differentiable in v0.11 // Use these alternative functions until the next release: extension Bool { public static func and(_ a: Bool, _ b: Bool) -> Bool { if a { if b { return true } } return false } // Usage: if Bool.and(condition1, condition2) instead of if condition1 && condition2 } // TODO: Remove when upgrading to Swift release with apple/swift/pull/33511 ``` This approach helps users understand current limitations, provides immediate solutions, and establishes clear upgrade paths when the framework evolves. --- ## Choose optimal data structures Select data structures based on their algorithmic complexity and usage patterns. Consider the tradeoffs between different structures (e.g., Vec vs HashMap) and their impact on performance. Key considerations: 1. Use HashSet/HashMap for O(1) lookups when uniqueness checking is primary concern 2. Prefer Vec when order matters or when performing sequential operations 3. Consider memory layout and cache locality for performance-critical code Example: ```rust // Suboptimal: Using HashMap when order matters let mut pieces: HashMap = HashMap::new(); // Better: Using Vec with HashSet for uniqueness let mut pieces: Vec<(String, f64)> = vec![]; let mut inserted: HashSet = HashSet::new(); // Best: Single pass implementation for pattern matching let mut prev = 0; let mut splits = Vec::with_capacity(inside.len()); for m in self.find_iter(inside) { if prev != m.start() { splits.push(((prev, m.start()), false)); } splits.push(((m.start(), m.end()), true)); prev = m.end(); } ``` --- ## Purpose-indicating descriptive names Choose names for variables, methods, parameters, and fixtures that clearly communicate their purpose, content, and behavior. Names should be self-documenting and consider future code evolution. For method names: - Use action verbs that precisely describe the method's effect - Prefer established patterns like `enable_xxx()`/`disable_xxx()` over ambiguous patterns like `with_xxx()`/`without_xxx()` ```python # Less clear: def with_padding(self, direction="right", ...): # ... # More clear: def enable_padding(self, direction="right", ...): # ... ``` For variables and parameters: - Choose names that describe what the value represents rather than its implementation details - Consider how names will work with future extensions ```python # Less descriptive - unclear what these files contain: @pytest.fixture(scope="session") def precompiled_files(data_dir): # ... # More descriptive - clearly indicates purpose and content: @pytest.fixture(scope="session") def serialized_files(data_dir): # ... ``` Maintain consistency in parameter naming across similar implementations to establish predictable patterns for API users. --- ## Prioritize readability over brevity When writing code, favor readability and maintainability over clever or compact solutions. Break down complex logic into smaller, well-named functions with clear purposes rather than embedding all logic in a single function. Follow these specific practices: 1. Extract related logic into separate, focused functions even when used only once: ```python # Instead of this: def patch_notebook(namespace, notebook): # ... some code ... if STOP_ATTR in request_body: # Many lines of complex start/stop logic here # ... more code ... # Prefer this: def patch_notebook(namespace, notebook): # ... some code ... if STOP_ATTR in request_body: start_stop_notebook(namespace, notebook, request_body) # ... more code ... def start_stop_notebook(namespace, notebook, request_body): # Start/stop logic extracted here ``` 2. Avoid complex one-liners that span multiple lines. Instead of: ```python resp = requests.request("GET", url, verify=False) if use_basic_auth else requests.request("GET", url, headers={"Authorization": "Bearer {}".format(token)}, verify=False) ``` Prefer: ```python if use_basic_auth: resp = requests.request("GET", url, verify=False) else: resp = requests.request( "GET", url, headers={"Authorization": "Bearer {}".format(token)}, verify=False ) ``` 3. For long lines, don't ignore linter warnings (like E501). Put arguments on separate lines: ```python # Instead of: @bp.route("/api/namespaces//tensorboards/", methods=["DELETE"]) # noqa E501 # Prefer: @bp.route( "/api/namespaces//tensorboards/", methods=["DELETE"] ) ``` This approach makes code easier to read, maintain, and debug, improving the overall quality of the codebase. --- ## Document code thoroughly Always include appropriate documentation in your code to improve readability, maintainability, and usability: 1. **Document all public APIs** with Go doc comments: ```go // MetricsExporter provides functionality for exporting metrics to Prometheus // and managing metrics collection within the application. type MetricsExporter struct { // fields... } // IncRequestCounter increments the request counter for the specified kind. // It tracks API usage patterns for monitoring purposes. func IncRequestCounter(kind string) { // implementation... } ``` 2. **Explain complex logic** with inline comments, especially when there are relationships between components or non-obvious behaviors: ```go // Update the CR status based on the ContainerState of the container // that has the same name as the CR if len(pod.Status.ContainerStatuses) > 0 { // implementation... } ``` 3. **Document code modifications** by adding TODOs with context for commented-out or temporary code: ```go // TODO(user): This endpoint is temporarily disabled until issue #123 is resolved // which addresses the race condition in the deployment creation process. // //// GetLatestKfdef returns latest kfdef status. ``` Following these practices ensures code is understandable to new team members, facilitates easier maintenance, and helps API consumers use your code correctly. Run tools like `go vet ./...` regularly to catch missing documentation on public elements. --- ## Teach by example Present concepts through clear, focused examples that demonstrate features positively rather than through comparisons or criticisms of alternative approaches. Allow readers to discover benefits through well-constructed examples rather than explicit statements about superiority. For instance, instead of: ```swift // OOP approaches have limitations because subclassing creates rigid hierarchies ``` Use an illustrative example: ```swift // Here's how protocols allow for flexible composition protocol Drawable { func draw() } struct Circle: Drawable { func draw() { /* implementation */ } } struct Square: Drawable { func draw() { /* implementation */ } } // Any type conforming to Drawable can be used here func renderShapes(_ shapes: [Drawable]) { for shape in shapes { shape.draw() } } ``` Keep examples simple and directly tied to the concept being taught. Complex examples with multiple concepts can confuse readers and obscure the main learning objective. When possible, make examples interactive so readers can experiment with the code and reach their own conclusions about its benefits. --- ## Append Only Compatibility When a generated API surface (e.g., an enum/type-id) is derived from the order of a registration list, treat that order as part of the public/binary API. Never reorder, insert in the middle, or remove/disable entries in that list—add new items only by appending at the end. Example (stable pattern): ```cmake # Stable ordered list; do not reorder existing entries. ncnn_add_layer(Reshape) ncnn_add_layer(ROIPooling) ncnn_add_layer(Scale) ncnn_add_layer(Sigmoid) # New layers must be appended only: ncnn_add_layer(HardSigmoid) ``` If a change must affect indices (e.g., removing an entry), require an explicit compatibility decision and versioning plan before merging, because it will break existing binaries/serialized models that depend on the numeric ids. --- ## Build Script Ordering In build/configuration files (e.g., CMakeLists), keep statements organized so that they are (1) scoped to the conditions that actually enable the associated sources/targets, and (2) ordered deterministically (e.g., alphabetical for registration lists). **Apply scope correctly** - If a source group/entry is only valid when a feature is enabled, place it *inside* the corresponding `if(WITH_...)` block. **Keep registrations sorted** - For repeated target/test registrations, sort by name (alphabetical) to reduce review noise and avoid accidental ordering drift. **Example (CMake)** ```cmake macro(ncnn_add_layer class) foreach(name IN LISTS ${class}) if(WITH_LAYER_${name}) if(WITH_LAYER_${name}_${arch}) # sources only for enabled arch source_group("sources\\layers" FILES "${CMAKE_CURRENT_SOURCE_DIR}/layer/${name}.cpp") source_group("sources\\layers\\${arch}" FILES "${CMAKE_CURRENT_SOURCE_DIR}/layer/${arch}/${name}_${arch}.cpp") if(WITH_LAYER_${name}_vulkan) # sources only for enabled Vulkan source_group("sources\\layers\\vulkan" FILES "${CMAKE_CURRENT_SOURCE_DIR}/layer/vulkan/${name}_vulkan.cpp") endif() endif() endif() endforeach() endmacro() # Tests: keep calls alphabetically ncnn_add_layer_test(AbsVal) ncnn_add_layer_test(ReLU) ``` This improves readability (future editors can see what is guarded by what) and produces cleaner, more predictable diffs. --- ## Enforce HTTPS protocol Always validate that URLs use the HTTPS protocol in both implementation code and validation error messages. Even if your application might handle HTTP-to-HTTPS redirects, enforce HTTPS from the outset as a security best practice to prevent man-in-the-middle attacks and data exposure. Example: ```javascript // Incorrect - allows HTTP if (!/^https?:\/\/\S+/.test(url)) { console.log('Invalid URL provided, must be like http*://*'); return false; } // Correct - enforces HTTPS only if (!/^https:\/\/\S+/.test(url)) { console.log('Invalid URL provided, must use HTTPS protocol'); return false; } ``` This helps ensure all communications are encrypted and prevents security vulnerabilities that can arise from initial insecure connections. --- ## Minimize object allocations Avoid creating unnecessary temporary objects or arrays which can impact performance through increased garbage collection and memory pressure. Apply these techniques to optimize memory usage: 1. **Direct assignment instead of temporary objects**: ```java // Inefficient: Creates a temporary array INDArray ret = Nd4j.valueArrayOf(new long[] {1, nOut}, gainInit); gainParamView.assign(ret); // Efficient: Direct assignment gainParamView.assign(gainInit); ``` 2. **Create exact-sized objects**: When you need a specific shape or size, create it directly rather than creating a larger object and extracting a subset: ```java // Inefficient: Creating larger array then extracting subset SDVariable b = SD.zerosLike(uHat).get(SDIndex.all(), SDIndex.all(), SDIndex.all(), SDIndex.interval(0, 1), SDIndex.interval(0, 1)); // Efficient: Create array with exact needed dimensions SDVariable b = SD.zeros(-1, inputCapsules, capsules, 1, 1); ``` 3. **Reuse immutable objects**: For thread-safe immutable objects like patterns, make them static class members: ```java // Inefficient: New Pattern object per instance private final Pattern splitPattern = Pattern.compile("..."); // Efficient: Shared across all instances private static final Pattern SPLIT_PATTERN = Pattern.compile("..."); ``` 4. **Defer object creation until necessary**: Use parameterized methods that only create objects when needed: ```java // Inefficient: Always creates String objects Preconditions.checkArgument(condition, "Labels array size " + labelSize + " does not match " + outputSize); // Efficient: Only formats if exception is thrown Preconditions.checkArgument(condition, "Labels array size %s does not match %s", labelSize, outputSize); ``` Implementing these practices consistently will reduce memory churn, decrease garbage collection pauses, and improve application performance, especially in memory-intensive operations. --- ## Contextualize and classify errors Always provide meaningful context when handling errors, and classify them appropriately based on their source. This improves debugging, helps users understand issues, and creates a consistent approach to error handling across the codebase. Follow these error handling principles: 1. **Use early returns with clear error checks**: ```go if err != nil { // Log error and/or return response return nil, fmt.Errorf("failed to process request: %v", err) } // Handle the success case ``` 2. **Provide context in error messages**: ```go // Instead of just returning or logging the raw error if _, err := w.Write([]byte(err.Error())); err != nil { log.Error(err) // Poor context // Better approach with context log.Error(fmt.Errorf("failed to write error response: %v", err)) } ``` 3. **Distinguish between error variables in nested scopes**: ```go err := json.NewDecoder(r.Body).Decode(&profile) if err != nil { // Handle first error if writeErr := json.NewEncoder(w).Encode(err); writeErr != nil { log.Error(fmt.Errorf("decode failed: %v, response write failed: %v", err, writeErr)) } return } ``` 4. **Classify errors properly**: ```go // For user input errors return &kfapis.KfError{ Code: int(kfapis.INVALID_ARGUMENT), Message: fmt.Sprintf("Project not specified: %v", err), } // For system/internal errors return &kfapis.KfError{ Code: int(kfapis.INTERNAL_ERROR), Message: fmt.Sprintf("Failed to create application: %v", err), } ``` 5. **Use consistent error types** throughout your codebase, and consider creating helper functions to reduce boilerplate: ```go func NewInvalidArgumentError(err error, msg string) *kfapis.KfError { return &kfapis.KfError{ Code: int(kfapis.INVALID_ARGUMENT), Message: fmt.Sprintf("%s: %v", msg, err), } } ``` --- ## Always secure your locks When using locks or other synchronization mechanisms in concurrent code, always release locks in a finally block to ensure they are released even when exceptions occur. Failure to do so can lead to deadlocks if other threads need the same lock. Additionally, choose the appropriate concurrency primitive for your specific use case. Using the wrong tool (like a Semaphore when a CountDownLatch is more appropriate) can lead to subtle bugs that are difficult to diagnose. Bad example: ```java public void updateModel(@NonNull Model model) { modelLock.writeLock().lock(); // If an exception occurs here, lock is never released! // Do work with the model... modelLock.writeLock().unlock(); } ``` Good example: ```java public void updateModel(@NonNull Model model) { modelLock.writeLock().lock(); try { // Do work with the model... } finally { modelLock.writeLock().unlock(); } } ``` For wait/notify patterns, consider whether a CountDownLatch or other higher-level concurrency primitive would be more appropriate than using raw locks or semaphores: ```java // Instead of this: private Semaphore semaphore = new Semaphore(0); public void update(Observable o, Object arg) { semaphore.release(Integer.MAX_VALUE); // Potential overflow! } // Consider this: private CountDownLatch latch = new CountDownLatch(1); public void update(Observable o, Object arg) { latch.countDown(); // Safe, can only transition once } public void waitTillDone() throws InterruptedException { latch.await(); // Properly propagate interruption } ``` --- ## Format for readability Code should be formatted to optimize readability. Apply these key practices: 1. **Maintain reasonable line length** (typically 100 columns) by breaking long lines of code. For function declarations with multiple parameters or long statements, wrap them across lines with proper indentation: ```swift // Instead of: func getMedianExecutionTime(iterationCount: UInt = 10, _ verbose:Bool = false, _ function: () -> ()) -> Double { // Use: func getMedianExecutionTime( iterationCount: UInt = 10, _ verbose:Bool = false, _ function: () -> () ) -> Double { ``` 2. **Leverage language syntax conventions** for cleaner code. In Swift, when a closure is the last argument, you can omit the parentheses: ```swift // Instead of: array.sorted(by: { s1, s2 in return s1 > s2 }) // You can write: array.sorted { s1, s2 in return s1 > s2 } ``` 3. **Use appropriate formatting for multiline strings**. In Swift, the indentation of multiline strings is aligned with the closing triple quotes, not the indentation in the source code: ```swift let quotation = """ This text will have leading whitespace aligned with the closing triple quotes. """ ``` These formatting practices improve code readability, reduce cognitive load, and make the codebase more maintainable. --- ## Mathematical precision matters When implementing mathematical algorithms, ensure precise terminology and correct implementation of mathematical concepts. This is especially important for complex domains like differentiation, optimization, or numerical methods. Three key practices to follow: 1. **Use mathematically accurate terminology in documentation** Descriptions should precisely match mathematical definitions. For example, when documenting differentiation: ```swift // INCORRECT: // Speaking in terms of elementary calculus, only functions that have derivatives can be differentiated. // CORRECT: // Speaking in terms of elementary calculus, only functions are "differentiable": only functions can *have derivatives* and can *be differentiated*. ``` 2. **Be explicit about algorithm limitations and edge cases** Clearly state when algorithms might fail or have special requirements: ```swift // GOOD EXPLANATION: // Differentiation can fail for several reasons: // * The function contains computation that cannot be differentiated // * The function is opaque (a function parameter with a non-@differentiable type) ``` 3. **Ensure mathematical correctness in example code** Example implementations must correctly implement the mathematical operations they demonstrate: ```swift // INCORRECT pullback implementation (missing parameter): @differentiating(sillyExp) func sillyDerivative(_ x: Float) -> (value: Float, pullback: (Float) -> Float) { let y = sillyExp(x) return (value: y, pullback: { _ in y }) // Incorrect: ignores parameter } // CORRECT implementation: @differentiating(sillyExp) func sillyDerivative(_ x: Float) -> (value: Float, pullback: (Float) -> Float) { let y = sillyExp(x) return (value: y, pullback: { v in v * y }) // Correct: uses parameter } ``` Following these practices ensures that algorithms are implemented correctly and are properly documented, making them more maintainable and less prone to subtle errors that can emerge when mathematical concepts are imprecisely translated to code. --- ## Stable configuration management Always ensure configuration values are managed consistently and sourced from stable locations. 1. Use defined constants instead of string literals for configuration values to improve maintainability and reduce errors when values change 2. Source configuration files from stable branches or tagged releases rather than potentially unstable sources like master 3. Clearly document when configuration values are environment-specific or will be overridden Example: ```typescript // ❌ Poor configuration management enum ConfigPath { V05 = 'v0.5-branch/config/kfctl_config.yaml', V06 = 'master/bootstrap/config/kfctl_gcp_iap.yaml' // Unstable source } const versionList = ['v0.7.0', 'v0.6.0']; // Hard-coded literals // ✅ Better configuration management enum Version { V05 = 'v0.5.0', V06 = 'v0.6.0', V07 = 'v0.7.0' } enum ConfigPath { V05 = 'v0.5-branch/config/kfctl_config.yaml', V06 = 'v0.6-branch/config/kfctl_gcp_iap.0.6.yaml' // Stable source } // Use constants and document environment-specific values const versionList = [ Version.V07, // For local testing, will be overwritten by env vars Version.V06 ]; ``` --- ## Document AI APIs completely When developing AI libraries and tools, provide comprehensive and accurate API documentation that helps users navigate complex functionality. Documentation should: 1. **Be explicit about method status and lifecycle:** - Clearly mark deprecated methods and provide better alternatives - Example from discussions: ```java // AVOID documenting only: List outputs = sd.outputs(); // Will be removed in future versions // BETTER documentation: // Finding outputs: Use sd.summary() to examine the graph structure // The outputs() method will be deprecated as it's not robust enough sd.summary(); // Examine to find outputs (variables that are inputs to no ops) ``` 2. **Document all execution patterns:** - Show both simple and advanced usage patterns - Explain alternatives for different scenarios - Example: ```java // For single output: INDArray out = sd.batchOutput() .input(inputs, inputArray) .output(outputs) .execSingle(); // For multiple outputs: Map results = sd.batchOutput() .input(inputs, inputArray) .output(outputs) .exec(); ``` 3. **Be transparent about limitations:** - Clearly document supported and unsupported features - Example: "SameDiff's TensorFlow import is still being developed, and does not yet have support for every single operation and datatype in TensorFlow. Almost all of the common/standard operations are importable and tested, however..." 4. **Hide implementation details:** - Focus on what users need to know, not internal mechanisms - Avoid mentioning internal components like "differential function factory" that most users will never need to interact with Structure documentation with common use cases first, followed by advanced topics, making it easy for users to find the information most relevant to their needs. --- ## Maintain proper capitalization Always use correct and consistent capitalization for product names, class names, and method names throughout code and documentation. Pay special attention to: 1. Framework names: `SameDiff` (not `samediff` or `Samediff`) 2. External frameworks: `TensorFlow` (not `Tensorflow`) 3. Method names: `SameDiff.importFrozenTF` (maintaining correct capitalization patterns) Consistent capitalization improves readability, searchability, and aligns with official naming conventions. When documenting naming behaviors, also be precise about how names are generated when not explicitly provided. Example: ```java // Incorrect SDVariable result = samediff.var("myVar", Nd4j.create(shape)); samediff.importFrozenTF(modelPath); // Correct SDVariable result = sameDiff.var("myVar", Nd4j.create(shape)); sameDiff.importFrozenTF(modelPath); ``` In documentation, maintain the same capitalization standards and be explicit about naming patterns, including when names are auto-generated based on operation names. --- ## Isolate test cases Create separate test functions for distinct functionality to improve test clarity and make failure points more obvious. When writing tests, avoid combining multiple scenarios into a single test function. Instead of adding platform-specific tests to an existing function: ```python def test_kf_is_ready(namespace, use_basic_auth, use_istio, app_path): # General Kubeflow tests util.wait_for_deployment(api_client, namespace, deployment_name) # Platform-specific tests (problematic) if platform == "gcp": # GCP-specific tests... ``` Create separate test functions: ```python def test_kf_is_ready(namespace, use_basic_auth, use_istio, app_path): # General Kubeflow tests only util.wait_for_deployment(api_client, namespace, deployment_name) def test_workload_identity(): # Skip if not on GCP if platform != "gcp": pytest.skip("Workload identity test only runs on GCP") # GCP-specific tests... ``` This organization makes it immediately clear which specific feature is failing when tests don't pass, simplifies debugging, and enables more effective test filtering when running targeted test suites. --- ## Follow Swift naming conventions Ensure code follows established Swift naming conventions and remains consistent with domain terminology: 1. Use standard Swift parameter labels (e.g., use `named:` instead of `called:`): ```swift // Incorrect func expectOne(called name: String, among candidates: [T]) throws -> T { ... } // Correct func expectOne(named name: String, among candidates: [T]) throws -> T { ... } ``` 2. Organize functions as methods on relevant types when appropriate: ```swift // Less idiomatic public func operandNames(for inst: Instruction) -> [String]? { ... } // More idiomatic extension Instruction { public var operandNames: [String]? { ... } } ``` 3. Use domain-specific terminology consistently (e.g., "operand names" not "registers" in SIL context) 4. Avoid redundancy in type names, especially in enum cases: ```swift // Redundant public indirect enum Type { case addressType(_ type: Type) } // Concise public indirect enum Type { case address(Type) } ``` 5. Maintain consistency with existing codebase conventions (e.g., using `inst` instead of `instr` for variables if that's the established pattern) --- ## Optimize hardware acceleration AI systems should use the most performant hardware acceleration libraries and carefully manage hardware-specific dependencies. Prefer Intel MKL over OpenBLAS for CPU operations as it provides superior performance for matrix calculations critical to neural networks and machine learning algorithms. Keep CPU and GPU dependencies cleanly separated to support different deployment scenarios. Example: ```xml org.bytedeco mkl ${mkl.javacpp.version} ${dependency.platform} ``` This approach ensures optimal performance for AI model training and inference while maintaining compatibility across different hardware configurations. --- ## Swift idiomatic naming Follow Swift's naming conventions to write more readable, maintainable code. The Swift language emphasizes clarity and expressiveness in naming: 1. **Avoid `get` prefixes** in function and method names. In Swift, properties and zero-argument methods serve this purpose without the prefix. ```swift // Avoid: func getTimeString(_ nanoseconds: Double) -> String { ... } // Prefer: func timeDescription(_ nanoseconds: Double) -> String { ... } ``` 2. **Name functions according to their purpose**, not their return type. The return type is already declared in the function signature. ```swift // Avoid: func colorString() -> String { ... } // Prefer: func description() -> String { ... } ``` 3. **Use Swift's shorthand type notation** for collections rather than the generic form. ```swift // Avoid: var timings: Array = [0.0] // Prefer: var timings: [Double] = [0.0] ``` 4. **Leverage abbreviated dot syntax** when the type context is already known. ```swift var rank: Rank = .queen // Instead of Rank.queen ``` These conventions align with the [Swift API Design Guidelines](https://swift.org/documentation/api-design-guidelines/) and help create a consistent codebase that other Swift developers can easily understand. --- ## Generic algorithm design When implementing generic algorithms in Swift, follow these best practices to improve code clarity and performance: 1. Place type constraints directly on associated types rather than at the protocol level: ```swift // Not recommended protocol SortingAlgorithm where Element: Comparable { associatedtype Element mutating func sort(_ array: inout [Element]) } // Recommended protocol SortingAlgorithm { associatedtype Element: Comparable mutating func sort(_ array: inout [Element]) } ``` 2. For filtering operations and predicates, evaluate whether a function type would be more appropriate than a custom protocol: ```swift // Using a protocol - more flexible but verbose protocol FilterPredicate { associatedtype Element func shouldKeep(_ item: Element) -> Bool } // Using a function type - often simpler for basic cases func filter(_ items: [T], predicate: (T) -> Bool) -> [T] { return items.filter(predicate) } ``` 3. Start with concrete implementations first, then extract protocols once patterns emerge. This helps you identify the minimal set of requirements needed for your generic algorithm to work effectively. --- ## User-friendly documentation examples Documentation should guide users toward best practices through clear examples. Begin with positive patterns before covering pitfalls, clarify all function parameters, and recommend appropriate methods for common tasks. When writing examples: 1. Use correct API naming conventions (e.g., 'INDArray' not 'IndArray') 2. Include parameter descriptions in comments for complex methods 3. Demonstrate the most appropriate methods for new users, avoiding potentially confusing APIs 4. Organize related functionality into logical sections 5. Indicate when showing only a subset of available functionality ```java // GOOD: Begin with positive examples, show parameter details INDArray x = Nd4j.linspace(1, 10, 5); // start, stop, count // [1.0000, 3.2500, 5.5000, 7.7500, 10.0000] // GOOD: Recommend beginner-friendly methods float[] vector = x.toFloatVector(); // Better than .data().asDouble() // GOOD: Group related functionality with proper naming // Reduction/accumulation operations: x.sum(); // Sum of all elements x.min(); // Minimum value x.max(); // Maximum value // BETTER: Move "don't do this" examples to the end // Common pitfalls to avoid: // INDArray x3 = x.add(x2); // Error if datatypes don't match ``` --- ## Use modern API methods {% raw %} When implementing algorithms with numerical libraries like ND4J, always prefer the most direct and type-safe API methods over older patterns. This improves code clarity, prevents subtle bugs, and often leads to better performance. Key practices: 1. Use `createFromArray` instead of `create` for array initialization, as it has clear overloads for all primitive types: ```java // Preferred: double arr_2d[][] = {{1.0,2.0,3.0},{4.0,5.0,6.0}}; INDArray x_2d = Nd4j.createFromArray(arr_2d); // Avoid: double[] flat = ArrayUtil.flattenDoubleArray(myDoubleArray); int[] shape = {rows, cols}; INDArray myArr = Nd4j.create(flat, shape, 'c'); ``` 2. Prefer direct parameter methods over shape arrays for common operations: ```java // Preferred: INDArray x = Nd4j.zeros(DataType.DOUBLE, 5); // Avoid: int[] shape = {5}; INDArray x = Nd4j.zeros(shape, DataType.DOUBLE); ``` 3. When handling arrays with different data types, explicitly use `castTo` for proper type conversion: ```java // When types don't match INDArray x = Nd4j.zeros(5, DataType.DOUBLE); INDArray y = Nd4j.zeros(5, DataType.INT); // Preferred: INDArray result = x.add(y.castTo(DataType.DOUBLE)); // Avoid - will throw exception: INDArray result = x.add(y); ``` Following these practices leads to more efficient algorithm implementations with fewer errors and better maintainability. {% endraw %} --- ## Follow Swift conventions When designing and documenting APIs in Swift, adhere to Swift's established naming conventions and documentation practices: 1. **Use correct initializer syntax**: Swift initializers should not form phrases with argument labels. Avoid prepositions in argument labels. ```swift // Incorrect let tensor = Tensor(fromNumpyArray: array) // Correct let tensor = Tensor(numpy: array) ``` 2. **Document APIs completely**: When referencing APIs in documentation, include both the original framework name and the complete Swift method signature with parameter names. ``` // Incomplete The saveV2 and restoreV2 ops are now supported. // Complete `SaveV2` (`Raw.saveV2(prefix:tensorNames:shapeAndSlices:tensors:)`), `RestoreV2` (`Raw.restoreV2(prefix:tensorNames:shapeAndSlices:dtypes:)`) ``` 3. **Use official terminology**: Maintain consistent terminology across documentation and code (e.g., use "operator" instead of "op"). 4. **Add API links**: Where possible, include links to API documentation to enhance discoverability and understanding. These practices ensure that your APIs are consistent with Swift ecosystem standards, making them more intuitive and discoverable for developers. --- ## Document AI implementation references When implementing AI algorithms or neural network operations, document the sources of specific implementation choices, especially for parameters or techniques that might appear arbitrary or unusual at first glance. Include references to established AI frameworks, research papers, or model implementations that informed your approach. This practice is particularly important for: 1. Magic numbers in neural network operations (like attention masks) 2. Mathematical formulas or equations adapted from specific libraries 3. Parameter choices that deviate from common defaults **Example:** ```cpp // Apply mask to attention weights // Using 1e9 as a large negative value for masked positions, // consistent with tensor2tensor implementation. // Note: BERT uses 1e4, GPT-2 uses 1e10 *weights += (*reshapedMask - 1) * 1e9; ``` This documentation helps future developers understand the rationale behind implementation decisions, facilitates accurate debugging, and enables informed modifications when updating the code. It also preserves knowledge about AI model compatibility that might otherwise be lost over time. --- ## Document environment variables When using configurable components, clearly document all relevant environment variables and their effects. Include examples showing how to set variables for common use cases, and specify any platform-specific differences. For environment variables that affect runtime behavior, clearly document when they need to be set and any order dependencies. For example, when documenting Python interoperability configuration: ```swift // Environment variables for Python configuration: // PYTHON_LIBRARY="~/anaconda3/lib/libpython3.7m.so" - Sets specific Python library (takes precedence) // PYTHON_VERSION="3.7" - Searches system paths for this Python version // PYTHON_LOADER_LOGGING=1 - Enables debug output for Python library loading // Note: Version selection must occur before any Python code is executed import Python // PythonLibrary.useVersion(3, 7) // Must be called immediately after import print(Python.version) // Now safe to use Python ``` Note platform-specific variations when they exist, as with the Python library path example: "The exact filename will differ across Python environments and platforms." Including such details helps users successfully configure their environment regardless of their system. --- ## Provide comprehensive examples API documentation should include complete examples that demonstrate all key usage patterns. When documenting related functions (like differentiation APIs), provide examples for each variant to show their relationships and differences. Include examples that showcase both basic usage and advanced patterns. For example, when documenting differentiation APIs: ```swift // Basic usage example let x: Float = 3.0 print(gradient(at: x, in: square)) // 6.0 // More comprehensive examples showing related functions // Show value with gradient print(valueWithGradient(at: x, in: square)) // (value: 9.0, gradient: 6.0) // Show pullback functionality let (result, pullback) = valueWithPullback(at: x, in: square) print(pullback(1.0)) // 6.0 // Show higher-arity function example let multiArgFunc: @differentiable (Float, Float) -> Float = { x, y in x * y } print(gradient(at: 2.0, 3.0, in: multiArgFunc)) // (3.0, 2.0) ``` Comprehensive examples help users understand the full capabilities of your API and how different functions relate to each other, which is essential for complex systems like automatic differentiation. When documenting complex APIs or concepts, ensure your examples cover different use cases that readers might encounter in real-world scenarios. --- ## Swift style consistency Maintain consistent Swift style conventions throughout all code, including examples in documentation and comments. Follow these specific guidelines: 1. Use 4-space indentation for all Swift code 2. Do not use spaces before colons in type declarations For example: ```swift // Correct struct Model: Differentiable { var parameter: Float var allDifferentiableVariables: AllDifferentiableVariables { get { return AllDifferentiableVariables(parameter: parameter) } set { parameter = newValue.parameter } } } // Incorrect struct Model : Differentiable { // space before colon var parameter: Float // 2-space indentation var allDifferentiableVariables: AllDifferentiableVariables { get { return AllDifferentiableVariables(parameter: parameter) } set { parameter = newValue.parameter } } } ``` When showing code patterns that may be truncated (like in documentation examples), use "..." to maintain symmetry and clarity of the pattern structure. ```swift // Complete pattern with "..." for consistency var allDifferentiableVariables: AllDifferentiableVariables { get { return AllDifferentiableVariables(x: x, y: y, ...) } set { x = newValue.x; y = newValue.y; ... } } ``` --- ## Training-aware ML APIs Design machine learning APIs with explicit parameters for distinguishing between training and inference phases rather than relying on global state or implicit context. This pattern enables concurrent training and testing, improves model reusability, and prevents subtle bugs in distributed training scenarios. ```swift // Instead of using global context: protocol Layer { func call(_ input: Input) -> Output // Implicit context is problematic } // Use explicit training parameters: protocol Layer { associatedtype Input: Differentiable associatedtype Output: Differentiable @differentiable(wrt: (self, input)) func call(_ input: Input, training: Bool) -> Output } // Implementation example: struct BatchNorm: Layer { var scale: Tensor var offset: Tensor @noDerivative var runningMean: Tensor @noDerivative var runningVariance: Tensor @differentiable(wrt: (self, input)) func call(_ input: Tensor, training: Bool) -> Tensor { if training { // Use batch statistics, update running statistics let batchStatistics = calculateBatchStatistics(input) updateRunningStatistics(batchStatistics) return normalize(input, using: batchStatistics) } else { // Use running statistics return normalize(input, using: (runningMean, runningVariance)) } } } ``` --- ## Preserve Backward Compatibility When making schema/proto changes, never remove (or repurpose) legacy layer parameters that existing models/configs rely on. For backward compatibility migrations, keep the old message/field definitions, mark them deprecated if appropriate, and implement translation/mapping to the new schema rather than dropping support. Guideline (Proto example): - If you need to evolve `LayerParameter`, add new optional fields with new tag numbers. - Do **not** delete existing BN parameter fields/messages used by older serialized configs. - If you must change behavior, keep the old schema elements and route them to the new implementation. Example pattern: ```proto message LayerParameter { // Legacy BN parameters must remain for old configs optional BNParameter bn_param = 45; // keep, don’t remove // New parameters added safely with new field numbers optional AnnotatedDataParameter annotated_data_param = 200; // If migrating semantics, keep BNParameter but implement conversion in code. } // Keep BNParameter definition for compatibility; optionally mark as deprecated. message BNParameter { optional FillerParameter filler = 3; } ``` Also add a migration/compatibility test: load an older BN-containing config/model and verify it still parses and runs. --- ## Prevent XSS vulnerabilities Never directly concatenate untrusted data (like user inputs or API responses) into HTML strings, as this creates cross-site scripting (XSS) vulnerabilities. Instead, create the HTML structure first, then populate content using safe DOM manipulation methods like jQuery's .text() or native JavaScript's .textContent that automatically escape special characters. Example - Vulnerable code: ```javascript innerHTML = '
'; innerHTML += 'Warning! ' + data.log + '
'; ``` Example - Secure approach: ```javascript // Create HTML structure innerHTML = `
× Warning!
`; // Safely set the content const $e = $("#error-msgs").html(innerHTML); $('.warning-log', $e).text(data.log); ``` --- ## Avoid eval function Never use the `eval()` function in Python code as it creates serious security vulnerabilities by executing arbitrary code at runtime. This can lead to code injection attacks when processing user inputs or data from untrusted sources. Instead of using `eval()` to convert strings to booleans or other types, use explicit type conversion or conditional logic: ```python # INSECURE - vulnerable to code injection: def setting_ctx(use_gpu): if eval(use_gpu): # code that uses GPU # SECURE - using explicit boolean conversion: def setting_ctx(use_gpu): if isinstance(use_gpu, str): use_gpu = use_gpu.lower() in ('true', 'yes', '1', 'y') if use_gpu: # code that uses GPU ``` For other type conversions, use appropriate functions like `int()`, `float()`, or `json.loads()` to safely parse data without executing code. --- ## Parameterize configuration scripts Configuration scripts should use variables for values that might change or are used in multiple places, such as paths, versions, and environment-specific settings. This improves maintainability, makes updates easier, and facilitates cross-platform support. When writing configuration or installation scripts: 1. Extract repeated values into variables defined at the top of the script 2. Use these variables throughout the script with appropriate syntax (${VARIABLE}) 3. Consolidate related commands where possible (e.g., combine multiple package installations) 4. Use appropriate command-line options for intended usage (e.g., `-y` for non-interactive execution) Example: ```bash # Bad approach - hardcoded values, separate commands sudo wget http://example.org/dist/maven/3.6.0/apache-maven-3.6.0-bin.tar.gz sudo tar -xf apache-maven-3.6.0-bin.tar.gz sudo rm -f apache-maven-3.6.0-bin.tar.gz sudo mv apache-maven-3.6.0/ apache-maven/ sudo apt-get install python-pip sudo apt-get install python-wheel sudo apt-get install python-dev # Good approach - parameterized and consolidated MAVEN_VERSION=3.6.0 cd /usr/local/src sudo wget http://example.org/dist/maven/${MAVEN_VERSION}/apache-maven-${MAVEN_VERSION}-bin.tar.gz sudo tar -xf apache-maven-${MAVEN_VERSION}-bin.tar.gz sudo rm -f apache-maven-${MAVEN_VERSION}-bin.tar.gz sudo mv apache-maven-${MAVEN_VERSION}/ apache-maven/ sudo apt-get install -y python-pip python-wheel python-dev python-setuptools ``` --- ## Fail fast clearly Detect and report errors as early as possible with detailed context to prevent silent failures and aid debugging. Validate inputs, states, and implementation completeness with appropriate exceptions that include relevant information. Key practices: 1. Validate parameters with explicit checks rather than silently ignoring invalid values: ```java // AVOID: Silently ignoring invalid parameters if (gamma > 0) this.gamma = gamma; // Negative gamma silently ignored // PREFER: Explicit validation with informative errors Preconditions.checkArgument(gamma > 0, "Gamma must be positive, got %s", gamma); this.gamma = gamma; ``` 2. Include relevant context in error messages to facilitate debugging: ```java // AVOID: Generic errors without context if (shape[dimension] != 1) { throw new ND4JIllegalStateException("Can squeeze only dimensions of size 1."); } // PREFER: Detailed exceptions with context Preconditions.checkState(shape[dimension] == 1, "Can squeeze only dimensions of size 1. Dimension %s has size %s. Shape: %s", dimension, shape[dimension], Arrays.toString(shape)); ``` 3. Use efficient validation patterns that avoid unnecessary object creation: ```java // AVOID: Always constructing error messages Preconditions.checkState(input.shape().length == 3, "3D input expected to RNN layer expected, got " + input.shape().length); // PREFER: Lazy message construction with format strings Preconditions.checkState(input.rank() == 3, "3D input expected to RNN layer, got %s", input.rank()); ``` 4. For unimplemented functionality, throw clear exceptions rather than allowing silent failures: ```java // AVOID: Unimplemented code with TODOs if (modelParamsSupplier != null) { val params = modelParamsSupplier.get(); if (params != null) { // TODO: We should propagate params across the workers } } // PREFER: Throw exception for unimplemented functionality if (modelParamsSupplier != null) { val params = modelParamsSupplier.get(); if (params != null) { throw new UnsupportedOperationException( "Parameter propagation to workers not yet implemented"); } } ``` --- ## Minimize cross-device transfers Data transfers between different compute devices (CPU/host to GPU/accelerator and back) can significantly impact performance in heterogeneous computing environments. Each transfer introduces latency and can block computation pipelines. Pay special attention to round-trip patterns where data moves from device A to B and back to A, as these create synchronization points that stall execution. For optimal performance: 1. Minimize data movement between host and accelerator during performance-critical sections 2. Batch transfers when possible rather than transferring small pieces repeatedly 3. Be especially wary of transfers inside loops that can repeatedly block computation Watch for problematic patterns like this: ``` for step in 0...1000 { let gradients = ... // on accelerator weights += gradients // on accelerator if cpuOnlyFunc(weights) == 0 { // forces data transfer to CPU and back weights += 1 // continues on accelerator after blocking } } ``` When designing APIs that operate across device boundaries, consider providing asynchronous alternatives that allow computation to continue without blocking while transfers occur in the background. --- ## Type-safe numerical algorithms When implementing numerical algorithms, always use appropriate data types to prevent overflow and preserve precision: 1. Use `Nd4jLong` or `auto` instead of `int` for array indices, dimensions, and strides, especially when working with potentially large data structures: ```cpp // Poor implementation - may cause overflow const int iStride2 = iH * iW; const int oStride2 = oH * oW; // Better implementation const Nd4jLong iStride2 = iH * iW; const Nd4jLong oStride2 = oH * oW; ``` 2. Implement direct type conversions between data types rather than casting through intermediate types (especially floating point) to maintain precision: ```cpp // Problematic - may lose precision due to floating point limitations z[i] = static_cast(static_cast(x[i])); // Better - direct conversion preserves precision z[i] = static_cast(x[i]); ``` This is particularly important when converting between integer types of different sizes, as floating-point conversions can cause inaccuracies for large values. For specialized numeric types, implement proper conversion operators between them to ensure consistent and precise data handling. --- ## Avoid environment-specific paths Always use environment variables or configuration mechanisms instead of hardcoding paths to compilers, tools, or directories. Hardcoded paths create dependencies on specific environments and break compatibility across different platforms and CI systems. Bad: ```bash #!/bin/bash CXX=/usr/bin/g++ ``` Good: ```bash #!/bin/bash # Use environment variable if set, otherwise use default CXX=${CXX:-g++} ``` For specialized environment paths, use specific environment variables that users can customize: Bad: ```bash export CMAKE_COMMAND="$CMAKE_COMMAND -D CMAKE_TOOLCHAIN_FILE=$HOME/raspberrypi/pi.cmake" ``` Good: ```bash # Allow users to specify RPI_HOME environment variable export RPI_HOME=${RPI_HOME:-$HOME/raspberrypi} export CMAKE_COMMAND="$CMAKE_COMMAND -D CMAKE_TOOLCHAIN_FILE=$RPI_HOME/pi.cmake" ``` This approach ensures scripts remain portable across different development environments, CI systems, and operating systems. --- ## Standardize metrics collection Use the appropriate metric types for the data being collected and consider centralizing monitoring code to ensure consistency across components. For accumulating values like request counts, use counters rather than gauges: ```go // CORRECT: Request counts should use counter metrics requestCounter = prometheus.NewCounterVec( prometheus.CounterOpts{ Name: "request_counter", Help: "Number of request_counter", }, []string{COMPONENT, KIND, NAMESPACE, ACTION, SEVERITY}, ) // INCORRECT: Don't use gauges for request counts // requestGauge = prometheus.NewGaugeVec(...) ``` To promote consistency, consider extracting common monitoring patterns into a shared library when multiple components need similar metrics. This ensures standardized naming conventions, label sets, and metric types across your application. Standard label keys (like component, namespace, severity) should be defined once and shared to prevent duplication and inconsistency.