Навіщо потрібна стабільність виводу

1. Що таке стабільний вивід CLI

Коли ви пишете свою першу CLI‑утиліту, може здаватися, що вивід — це просто fmt.Println(...) і «ну, працює ж». Але якщо ваша програма живе довше ніж п’ять хвилин, поруч із нею з’являються люди, скрипти, пайпи, CI, тести… і кожен із них починає сприймати вивід як контракт. Тобто як обіцянку: «ось так виглядатиме результат, і на нього можна покластися».

Стабільний вивід — це коли за однакових вхідних даних програма друкує однаковий результат: ті самі рядки, у тому самому порядку, з тими самими пробілами, табуляціями та переносом рядка наприкінці. Іноді це звучить як «максимально нудно», але в інженерії нудно — це комплімент. В офіційному блозі Go навіть є думка, що «boring is stable» («нудно — означає стабільно») у контексті сумісності та передбачуваності.

Щоб не зависати в абстракціях, введемо робоче визначення.

Стабільність виводу CLI — це сукупність правил, які роблять результат команди передбачуваним: однакові дані → однаковий текст/JSON, без «плаваючого» порядку, без випадкових часових міток, без сміття в stdout, з однаковими заголовками та колонками.

І так, це напряму впливає на довіру до вашої програми. Користувач може пробачити, що ви не пофарбували вивід у 17 відтінків. Але користувач, як і CI, не пробачить, що «вчора список був таким, а сьогодні — таким самим, але в іншому порядку».

2. Хто споживає вивід: людина, скрипт і тест

Якщо ви пишете CLI тільки для себе, легко потрапити в пастку думки: «Я ж дивлюся на це очима — мені нормально». Але CLI майже ніколи не лишається тільки «для очей». І тут з’являються три типи споживачів виводу, у кожного — свій біль.

Людина читає вивід очима й хоче, щоб він був зрозумілим і незмінним: порядок задач не стрибає, заголовки на місці, а нові версії програми не перетворюють звичний вивід на квест «знайди, де тепер колонка STATUS».

Скрипт читає вивід як потік символів. У скрипта немає емпатії. Він не здогадуватиметься, що ви «лише додали слово Total: посеред виводу». Скрипт або розпарсить, або зламається. І зазвичай ламається вночі, у п’ятницю, на проді — просто щоб ви не розслаблялися.

Тест (і особливо снапшот‑підхід, який ми будемо використовувати в курсових перевірках) порівнює очікуваний текст із фактичним. У Go це видно навіть на прикладі example‑тестів: фреймворк захоплює те, що ви друкуєте в stdout, і порівнює з коментарем // Output:. Якщо вивід «тремтить», тест падатиме то так, то сяк.

Тобто стабільність виводу — це не «краса», а зниження вартості життя проєкту: менше хибних падінь тестів, менше зламаних пайпів, менше «а в мене на комп’ютері по-іншому».

3. Звідки береться нестабільність виводу

Зазвичай вивід стає нестабільним не тому, що розробник зла людина, а тому що розробник… людина, і в нього є map, time.Now() і бажання «трошки покращити повідомлення».

Давайте розберемо найчастіші причини. Щоб було простіше тримати їх у голові, зведемо все в таблицю. Це не «формальна математика», а реальний список граблів, на які наступають навіть досвідчені хлопці, особливо коли поспішають.

Ідея тут проста: вивід має бути нудним і повторюваним. Комп’ютери, взагалі-то, саме в цьому й сильні: вони старанно повторюють одне й те саме. Навіть в офіційному матеріалі про генератори випадкових чисел є гарне формулювання: «комп’ютери не випадкові… вони намагаються виконувати програми однаково щоразу» — і саме цього ми хочемо від виводу.

4. Стратегія: спочатку дані, потім друк

Зараз ми почнемо розвивати наш навчальний CLI‑застосунок задач, умовно назвемо його todo. Поки без файлів, без JSON‑режимів і без гарних таблиць: сьогодні нам важливо впіймати принцип «вивід — контракт».

Почнімо з моделі задачі. Вона буде простою, щоб не відволікати від теми виводу.

package main

type Task struct {
	ID    int
	Title string
	Done  bool
}

Тепер уявімо, що задачі ми поки зберігаємо в map[int]Task — це типово: за ID зручно діставати. І ось ви хочете вивести список.

Нестабільний друк із map

Після цього заголовка хочеться зробити вдих і зізнатися: майже всі так робили. Я теж. А потім тести почали жити своїм життям.

package main

import "fmt"

func printTasksBad(tasks map[int]Task) {
	for id, t := range tasks {
		fmt.Printf("%d: %s (done=%v)\n", id, t.Title, t.Done)
	}
}

Проблема в тому, що порядок обходу map у Go не гарантується. Це означає: ви можете отримати різний порядок рядків між запусками. Іноді здається, що порядок однаковий, але це саме той випадок, коли програма відкладає сюрприз на потім.

І ось тут народжується головний принцип дня: стабільність — це не «налаштування fmt», а архітектура пайплайна.

Детермінізуємо: map → []Task → sort

Нам потрібно зробити два кроки: спочатку отримати список задач у вигляді []Task, потім відсортувати його і лише після цього друкувати.

package main

import "sort"

func tasksToSlice(tasks map[int]Task) []Task {
	out := make([]Task, 0, len(tasks))
	for _, t := range tasks {
		out = append(out, t)
	}
	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
	return out
}

Зверніть увагу: ми лише підготували дані. Жодного fmt тут немає. Це дуже важлива звичка: друк — в одному місці, підготовка — в іншому.

І тепер друк стає передбачуваним:

package main

import "fmt"

func printTasksStable(tasks []Task) {
	for _, t := range tasks {
		fmt.Printf("%d: %s (done=%v)\n", t.ID, t.Title, t.Done)
	}
}

Тепер у нас є стабільний порядок — за ID. Це вже контракт: «список задач завжди відсортований за ID у зростаючому порядку».

5. Практика: робимо вивід нудним і передбачуваним

Пайплайн виводу: отримали → підготували → надрукували

Коли ви усвідомили, що «друк — це контракт», наступним кроком стає дуже проста, але потужна структура: пайплайн виводу. Він допомагає не лише стабілізувати результат, а й тримати код читабельним.

Можна уявити, що вивід — це не одна кнопка «друк», а невелика конвеєрна лінія на заводі: сировина (дані) проходить через операції (підготовка), і на виході ми отримуємо продукт (текст/JSON). Якщо ви почнете свердлити корпус на етапі, коли деталі ще немає, — буде криво.

Пайплайн виглядає так:

flowchart LR
    A[Джерело даних] --> B[Підготовка списку]
    B --> C[Стабілізація порядку]
    C --> D[Рендер у stdout]
    E[Помилки/діагностика] --> F[stderr]

З погляду коду це можна оформити однією функцією, яка читабельно показує порядок кроків:

package main

func listPipeline(tasks map[int]Task) []Task {
	items := tasksToSlice(tasks) // включно із сортуванням
	return items
}

Так, поки це «надто просто». Але саме такі «надто прості» функції потім рятують проєкт, коли додаються фільтри, сортування за різними полями та кілька форматів виводу. Якщо заздалегідь закріпити ідею пайплайна, розширення не перетвориться на кашу з fmt.Printf усередині if.

Розділяємо stdout і stderr

Багато новачків щиро думають: «Ну я ж просто додам fmt.Println("OK"), щоб було зрозуміліше». Для людини це справді зручніше. Але якщо команда використовується в пайпі, ви щойно заклали міну.

Важливо змінити мислення: stdout — це «дані», а stderr — це «розмова програми про свої проблеми». Якщо ви змішаєте їх, користувач може не помітити. А от скрипт помітить, але вже тоді, коли буде пізно.

Правило просте: усе, що є результатом команди, — у stdout. Будь-які помилки, попередження, usage та підказки — у stderr.

Міні‑приклад:

package main

import (
	"fmt"
	"os"
)

func warn(msg string) {
	fmt.Fprintln(os.Stderr, "warning:", msg)
}

І тепер уявіть, що у вас є команда todo list, яка по stdout друкує задачі. Якщо ви випадково надрукуєте «Loaded 10 tasks» у stdout, а користувач робить todo list | wc -l, то wc порахує і «Loaded 10 tasks» також. Скрипт не винен. Винні ми.

Тут же народжується ще один мікроконтракт: у режимі, де stdout — це дані, stdout має бути «чистим». Без банерів, без «успіх!», без «натисніть лайк і підпишіться».

Дрібниці формату: перенесення рядка та пробіли

Іноді здається, що «та яка різниця, є \n наприкінці чи ні». Різниця з’являється, коли ви порівнюєте рядки в тесті, склеюєте виводи, використовуєте diff, зберігаєте golden‑файли тощо. Тоді один «зайвий» або «відсутній» перенос рядка стає вічним дрібним болем.

Просте правило: будь-яка команда, яка друкує текстовий результат, завершує вивід переносом рядка. Це робить вивід дружнім до термінала й передбачуваним для порівняння.

У Go це зазвичай означає, що ви надаєте перевагу fmt.Println(...) або fmt.Fprintf(out, "... \n"), а не забуваєте \n у Printf.

package main

import "fmt"

func printOneLine() {
	fmt.Println("hello") // hello
}

Із пробілами схожа історія. Якщо ви то ставите один пробіл, то три, то таб, то «вирівняю руками», ви гарантовано отримаєте ситуацію «на око нормально, а тест упав». Вивід — це рядок байтів, і в нього немає поняття «ну, приблизно однаково».

Тому «стабільність» — це ще й дисципліна: один стиль розділювачів, один стиль заголовків, один стиль булевих значень. Наприклад, ви вирішуєте: done=true/false — і тримаєтеся цього. Або вирішуєте: DONE/UNDONE — і тримаєтеся його. Головне — не змінювати «за настроєм».

Чому без детермінізму не працюють тести на вивід

Ми ще не розбираємо тестування CLI глибоко, але тут важливо зрозуміти мотивацію: тести на вивід стають можливими лише тоді, коли вивід детермінований.

Зручно згадати example‑тести Go: приклад у документації може одночасно бути тестом, тому що go test захоплює stdout і порівнює його з очікуваним // Output:. І якщо у виводі ви залежите від порядку map або від поточного часу, «приклад‑тест» перетворюється на лотерею.

Детермінізм робить вивід «артефактом», який можна порівняти: учорашній вивід = сьогоднішній вивід за тих самих даних. І тоді у вас з’являється суперсила: ви можете автоматично ловити регресії, коли хтось «трошки поправив формат».

У термінах розробки це виглядає так: ви не сперечаєтеся «а нормально тепер друкується список?», а просто бачите, що тест сказав: «формат змінився». А далі вже вирішуєте, це усвідомлена зміна контракту чи випадкова поломка.

Міні‑приклад: todo list зі стабільним виводом

Давайте зберемо маленький, але цілісний шматок програми, щоб було відчуття: «Я можу це запустити, і воно буде стабільним».

Ми не робимо повноцінну архітектуру і не підключаємо зберігання. Ми просто фіксуємо, що навіть на мок‑даних ми вміємо вивести список задач так, щоб він не стрибав.

package main

import "fmt"

func main() {
	tasks := map[int]Task{
		2: {ID: 2, Title: "buy milk", Done: false},
		1: {ID: 1, Title: "learn Go", Done: true},
	}

	items := tasksToSlice(tasks)
	printTasksStable(items)

	fmt.Print("") // нічого «службового» не друкуємо в stdout
}

Якщо ви запустите це багато разів, порядок буде завжди однаковий:

1: learn Go (done=true)
2: buy milk (done=false)

І ось це відчуття — «можу повторити запуск і отримати те саме» — і є основою стабільного виводу.

6. Типові помилки під час проєктування стабільного виводу

Помилка №1: «range по map і одразу друкую — чого там».
Поки даних мало, здається, що порядок «приблизно однаковий». Але насправді ви просто вдало потрапили у випадковість. Щойно ви почнете порівнювати вивід у тестах або використовувати його в скриптах, порядок почне тремтіти. Лікується відокремленням підготовки даних від друку: map → []Task → sort → render.

Помилка №2: «я додам у stdout трошки пояснень, це ж зручно».
Зручно для людини, але ламає пайпи. Результат команди має бути чистим, особливо якщо його передбачається парсити або передавати далі. Будь-які «Loaded X tasks», «OK», «Done» мають іти або в stderr, або бути опційними, наприклад через прапорець --verbose, але сам прапорець — це окреме дизайнерське питання.

Помилка №3: змішування фільтрації, логіки та друку в одній функції.
Щойно в коді з’являються конструкції на кшталт «якщо задача підходить — друкуємо», ви втрачаєте контроль над порядком, форматом і над тим, що взагалі є результатом команди. Значно стабільніше спочатку зібрати список «що виводимо», а потім однією функцією визначити «як виводимо».

Помилка №4: «плаваючі дрібниці» — забутий \n, різні пробіли, різні заголовки.
Це звучить як дрібниця, поки ви не побачите падіння тесту через один символ. Якщо ви вважаєте вивід контрактом, то контракт — це кожен байт. Дисципліна тут нудна, але рятівна: єдиний стиль рядків і перенос рядка наприкінці.

Помилка №5: випадкові дані у виводі (час, випадкові id, хеші) без потреби.
Дуже хочеться додати «для відладки», але якщо це потрапляє в основний вивід команди, ви вбиваєте детермінізм. Такі речі або не друкуються за замовчуванням, або друкуються в stderr як діагностика, або вмикаються окремим режимом.