УРОК · Стандарты и поддерживаемый код

Документация и технический долг

Опубликовано Автор: Соловьёва Мария Андреевна

После Patterns README всё ещё говорит о структуре «после первого проекта» и содержит числа чужого локального опыта. Обновим инструкцию и проверим её без старой SQLite.

Разберём по шагам

README должен помочь запустить текущий код из чистой папки, а не обещать одинаковое число строк на всех компьютерах. В проекте уже есть src/note-rules.php, src/note-store.php, поиск q и необязательный NOTES_DB_PATH. Зафиксируем их и отдельно запишем открытый долг: change-note.php делает UPDATE без isValidTitle, поэтому общее правило названия пока не защищает все входы. Документ о долге не заменяет исправление.

Слова, которые пригодятся

README
Файл с инструкцией для запуска и проверки проекта. Новый участник должен найти в нём команды для чистой копии и текущие ограничения.
Чистая копия
Новая папка с кодом без старой локальной базы и скрытой истории запуска. Она показывает, достаточно ли описанных команд для старта.
Технический долг
Известное неполное решение, для которого записаны риск и условие исправления. Здесь CLI-UPDATE ещё не использует общую проверку названия.

Документация устаревает вместе с кодом. Проверка в отдельной папке без .git и SQLite заставляет пройти именно записанный порядок, а не случайно воспользоваться своей старой базой. Число строк после add-note.php в чистой копии — одна, но в давно используемом проекте оно другое; старый результат 2 -> 3 остаётся только исторической заметкой.

Технический долг — известное ограничение с последствием и условием исправления. maintenance-notes.md фиксирует, что CLI-обновление обходит правило, но не создаёт фиктивного владельца или 403. Исправление этого входа и проверка прав потребуют отдельной задачи.

Рабочий пример

Текущая структура: public/index.php, templates/home.php,
src/db.php, src/note-rules.php, src/note-store.php.
GET / показывает список; GET /?q=... ищет по названию.
POST / добавляет заметку и возвращает 303; неверный ввод остаётся на форме.
data/*.sqlite — локальные данные вне Git. NOTES_DB_PATH выбирает существующую копию базы;
без него используется data/notes.sqlite. Входа и владельцев записей пока нет.

Практика

Приведите README к текущему проекту и запустите его в новой папке. Так инструкция станет проверенной, а оставшееся ограничение будет видно следующему разработчику.

  1. В Visual Studio Code откройте notes-php/README.md. Найдите старую строку «Структура после первого проекта: …» и замените её строками примера; существующий порядок mkdir data, php setup.php, php add-note.php, php migrate-created-at.php, php -S localhost:8000 -t public оставьте. Строку с числами «2 -> 3» пометьте как пример прежнего локального опыта, а не ожидаемый результат нового клона. Сохраните Ctrl+S.
  2. В корне notes-php рядом с README создайте maintenance-notes.md. Запишите: «Долг: change-note.php выполняет UPDATE без isValidTitle; риск — пустое или длинное название через CLI; условие закрытия — подключить проверку к этому входу и повторить тест на отдельной SQLite. Сейчас входа и проверки владельца нет». Сохраните Ctrl+S. Проверьте через поиск VS Code, что change-note.php действительно содержит UPDATE, а isValidTitle там не вызывается.
  3. Из корня notes-php в PowerShell выполните $origin = (Get-Location).Path, $probe = Join-Path $env:TEMP ('notes-php-doc-' + [guid]::NewGuid().ToString('N').Substring(0,8)), New-Item -ItemType Directory -Path $probe, затем Copy-Item -LiteralPath @((Join-Path $origin 'public'),(Join-Path $origin 'src'),(Join-Path $origin 'templates'),(Join-Path $origin 'setup.php'),(Join-Path $origin 'add-note.php'),(Join-Path $origin 'migrate-created-at.php'),(Join-Path $origin 'README.md'),(Join-Path $origin 'config.example.ps1')) -Destination $probe -Recurse. Копия не содержит .git и старые data/*.sqlite. Перейдите в неё Set-Location $probe, выполните mkdir data, php setup.php, php add-note.php, php migrate-created-at.php; ожидайте готовую таблицу, один добавленный id и сообщение о миграции. Выполните php -l public/index.php и php -l src/note-store.php.
  4. В этой копии запустите php -S localhost:8000 -t public. Во втором терминале PowerShell выполните curl.exe -i http://localhost:8000/ и curl.exe -i --data "title=Docs&body=Check" http://localhost:8000/: ожидайте 200 со списком и 303 Location: /; повторный GET показывает Docs. Остановите сервер Ctrl+C. Вернитесь в исходную папку Set-Location $origin; выполните git diff --check и git status --short. В README не должно быть пароля, обещания публичной проверки или утверждения, что документированный долг уже закрыт.

Как проверить себя

По обновлённому README чистая копия создаёт базу, проходит миграцию и открывает страницу; maintenance-notes.md называет реальный обход правила и критерий закрытия, не выдавая его за исправленный.

Если не получилось
  • В чистой копии нет data? Это ожидаемо: создайте её командой mkdir data до php setup.php.
  • php не найден в новом терминале? Вернитесь к PHP1, проверьте php -v после открытия нового терминала и только затем повторите команды.
  • В чистой копии ошибка undefined function insertNote? Проверьте, что скопировали всю папку src, включая note-store.php, и public/index.php подключает этот файл.