Тема: coding-practice
-
Проектирование консольной утилиты на Python: argparse, main() и коды возврата
Разместите интерфейс в функции main(argv) -> int, зарегистрированной как консольный скрипт; проверяйте аргументы через type и choices в argparse; следуйте соглашению о кодах возврата (0 — успех, 2 — ошибка использования, 1 — прочий сбой, коды sysexits — только если они задокументированы); выводите результаты в stdout, а диагностику — в stderr; обрабатывайте SIGINT и разорванные каналы (broken pipe).
-
Соглашения внедрения зависимостей в .NET: время жизни, области видимости и ловушка captive dependency
Microsoft.Extensions.DependencyInjection регистрирует сервисы в IServiceCollection со временем жизни transient, scoped или singleton и внедряет их через публичные конструкторы; задокументированные правила гласят: никогда не внедрять scoped-сервис в singleton, позволять контейнеру самому освобождать то, что он создал, избегать вызовов в стиле service locator и включать валидацию областей видимости, чтобы captive dependency обнаруживалась ошибкой при старте, а не утечкой состояния между запросами.
-
Комментарии с информацией, которую не передаёт код
Пишите комментарии о причинах, ограничениях и неочевидных последствиях, а не пересказывайте код. Держите их рядом с описываемым кодом, удаляйте, когда исчезает причина, и предпочитайте комментарию более удачное имя или тест.
-
Рефакторинг небольшими проверяемыми шагами
Рефакторинг меняет структуру, не меняя поведения. Малые шаги с успешными тестами между ними и отдельные коммиты для рефакторинга и изменений поведения делают процесс безопасным и удобным для ревью.
-
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 с помощью JSON Schema
JSON Schema описывает допустимую структуру документа: типы, обязательные ключи, перечисления, форматы и ограничения. Это позволяет проверять входные данные на любом языке до их обработки; задавайте additionalProperties явно.
-
Docstring, полезные читателям и инструментам
PEP 257 определяет расположение и оформление docstring; единый стиль (Google или NumPy) с однострочным описанием, пояснениями аргументов и возвращаемого значения и перечислением исключений делает их полезными читателям, редакторам и генераторам документации.
-
Числа с плавающей точкой: почему 0.1 + 0.2 не равно 0.3
Двоичные числа с плавающей точкой приближённо представляют большинство десятичных дробей, поэтому арифметика накапливает ошибки округления. Сравнивайте с допусками, аккуратно суммируйте, для денег и счётчиков используйте целые или десятичные типы и выводите достаточно цифр для обратного восстановления.
-
Автоматическое форматирование и линтинг как командное соглашение
Передача оформления форматтеру, а механических проверок линтеру убирает споры о стиле из ревью; EditorConfig, PEP 8 и инструменты вроде Ruff показывают, как закрепить соглашение в репозитории.
-
Масштабирование признаков и кодирование категорий: что преобразовывать; обучайте преобразователи только на тренировочных данных
Моделям на основе расстояний и градиентов нужны числовые признаки в сопоставимых масштабах (StandardScaler, MinMaxScaler, RobustScaler); категориальные столбцы превращаются в числа с помощью one-hot, порядкового или целевого кодирования в зависимости от числа категорий и типа модели. Каждый преобразователь обучается на тренировочной части и без изменений применяется к валидационным, тестовым и рабочим данным.
-
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, проверка и ограниченные повторы
Опишите целевую запись через JSON Schema с additionalProperties false, запросите у модели именно эту форму, проверяйте каждый ответ настоящим валидатором и повторяйте запрос ограниченное число раз, передавая ошибку проверки. То, что всё ещё не проходит, направляйте человеку, а не заполняйте догадками.
-
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