主题： coding-practice
-
设计 Python 命令行工具：argparse、main() 与退出码
将接口放入注册为控制台脚本的 main(argv) -> int 函数中，用 argparse 的 type 和 choices 做校验，遵循退出码惯例（0 表示成功，2 表示用法错误，1 表示其他失败，仅在有文档说明时才使用 sysexits 代码），将结果输出到 stdout、诊断信息输出到 stderr，并妥善处理 SIGINT 和管道中断。
-
.NET 依赖注入惯例：生命周期、作用域与“被困依赖”陷阱
Microsoft.Extensions.DependencyInjection 会把服务以 transient（瞬时）、scoped（作用域）或 singleton（单例）三种生命周期之一注册到 `IServiceCollection` 上，并通过公共构造函数注入；官方文档规定的规则是：绝不能把 scoped 服务注入 singleton 中，容器创建的对象应由容器自己释放，应避免使用服务定位器（service locator）式调用，并应启用作用域校验，使“被困依赖”在启动时就报错，而不是在多个请求之间悄悄泄漏状态。
-
用注释传达代码无法表达的信息
注释应解释原因、约束和不明显的后果，而不是复述代码。让注释紧邻其描述的代码，在理由不再成立时删除；能用更好的命名或测试表达时，应优先采用这些方式。
-
以经过验证的小步骤进行重构
重构改变结构而不改变行为。每次只做很小的改动，在步骤之间保持测试通过，并将重构提交与行为变更分开，能让过程安全且便于审查。
-
Technische Schulden als bewusste Entscheidung mit Buchführung
Cunninghams Metapher: Nicht ganz richtiger Code ist ein Kredit, jede Minute Mehrarbeit daran ist der Zins. Die Metapher trägt nur, wenn die Schuld bewusst aufgenommen, notiert und regelmässig bewertet wird; als Sammelbegriff für alles Unschöne oder als Entschuldigung für Schlamperei ist sie wertlos.
-
Working practices for an AI agent changing a codebase
Read before writing, reproduce before fixing, change in small verified steps, run the project's own checks, never retry writes blindly, and report exactly what was tested; a methodology for agents that edit code.
-
TypeScript narrowing: unions, unknown and any
TypeScript shrinks a union type inside a branch after typeof, instanceof, in, equality and truthiness checks or a user-defined type predicate; discriminated unions plus a never check give exhaustiveness. unknown accepts any value but forbids using it until narrowed, whereas any switches checking off.
-
Technical debt as a metaphor and as a decision
Technical debt describes the future cost of a shortcut; the metaphor is useful when the debt is deliberate and tracked, and misleading when it excuses careless work or is used to describe every imperfection.
-
让标识符名称表达代码意图
使用领域词汇命名，说明某个事物是什么或做什么，名称长度应与其作用范围相称。避免把额外编码塞进名称、使用缩写或暗示错误的类型，并随着理解加深及时重命名。
-
统一 JSON 字段的命名与大小写
为属性名选定一种大小写约定并在所有地方使用：Google 的 JSON 风格指南和 ProtoJSON 使用 lowerCamelCase，许多 API 使用 snake_case。除大小写外，还要让名称有明确含义，将枚举表示为字符串、时间戳表示为 RFC 3339 字符串、64 位整数表示为字符串。
-
Python 上下文管理器：保证清理操作执行
with 语句在代码块前后调用 __enter__ 和 __exit__，使文件、锁和连接在发生异常时也能被释放；contextlib.contextmanager 可将生成器转换成上下文管理器。
-
使用 JSON Schema 验证 JSON
JSON Schema 描述文档允许的结构，包括类型、必需键、枚举值、格式和边界，使各种编程语言都能在处理输入之前验证它；应明确设置 additionalProperties。
-
让工具和读者都能有效使用的文档字符串
PEP 257 规定了文档字符串的位置和格式；采用一致的风格（Google 或 NumPy），包含单行概述、参数与返回值说明以及抛出的异常，便能让读者、编辑器和文档生成器有效使用它们。
-
浮点数：为什么 0.1 + 0.2 不等于 0.3
二进制浮点数只能近似表示大多数十进制小数，因此运算会累积舍入误差。应按容差比较、谨慎求和，金额和计数使用整数或十进制类型，并输出足够位数以便往返还原。
-
将自动格式化和代码检查作为团队约定
把布局交给格式化工具，把机械检查交给代码检查器，可以消除评审中的风格争论；EditorConfig、PEP 8 以及 Ruff 等工具展示了如何将约定编码到仓库中。
-
特征缩放与类别编码：变换什么，以及只在训练数据上拟合
基于距离和梯度的模型需要数值特征具有可比的尺度（StandardScaler、MinMaxScaler、RobustScaler）；类别列则根据类别数量和模型类型，通过独热编码、序数编码或目标编码转换为数值。每个变换器都在训练划分上拟合，再原样应用于验证、测试和生产数据行。
-
Protocol classes: structural typing for duck-typed Python
A typing.Protocol declares the methods and attributes a consumer needs; any object that has them satisfies the type without inheriting from it. Define protocols next to the code that depends on them, keep them minimal, and use runtime_checkable only where isinstance is really needed.
-
机器学习实验的可复现性：随机种子、环境、数据与确定性的边界
重新运行实验并得到同一个数值，需要显式传入固定的随机状态、锁定库版本、明确数据集和划分，同时认识到 GPU 内核和库的新版本仍可能改变结果；该流程尽可能让运行可重复，并记录无法重复的部分。
-
利用 JSON Schema、验证与有限重试从文档中提取结构化数据
将目标记录定义为 additionalProperties false 的 JSON Schema，要求模型严格按该结构输出，用真正的验证器检查每个响应，并把验证错误反馈到提示中，在限定次数内重试。仍然失败的记录应交给人工，而不是猜测。
-
NULL in SQL: three-valued logic and its traps
NULL means unknown, so comparisons with NULL yield unknown rather than true or false; WHERE filters drop unknown rows, NOT IN with a NULL matches nothing, and aggregates skip NULLs. Use IS NULL, IS DISTINCT FROM and COALESCE deliberately.
机器可读： JSON