Документация и технический долг
После 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 к текущему проекту и запустите его в новой папке. Так инструкция станет проверенной, а оставшееся ограничение будет видно следующему разработчику.
- В 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. - В корне
notes-phpрядом с README создайтеmaintenance-notes.md. Запишите: «Долг:change-note.phpвыполняетUPDATEбезisValidTitle; риск — пустое или длинное название через CLI; условие закрытия — подключить проверку к этому входу и повторить тест на отдельной SQLite. Сейчас входа и проверки владельца нет». СохранитеCtrl+S. Проверьте через поиск VS Code, чтоchange-note.phpдействительно содержитUPDATE, аisValidTitleтам не вызывается. - Из корня
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. - В этой копии запустите
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подключает этот файл.
Чтобы сохранять прогресс, войдите или зарегистрируйтесь.
Следующий материал ↗