Dlaczego zaczynać pracę od pliku README?
(w skrócie) Aby za 5 minut, które zajmie Ci napisanie krótkiej notatki wiedzieć dlaczego, jak i jaki kod napisać, a za 4 miesiące gdy będziesz potrzebować dopisać dwie litery wiedzieć gdzie szukać odpowiedniej linijki w kodzie.
Czym jest plik README?
Jak sama nazwa wskazuje prosi się on o przeczytanie. Zawiera on zwykle informacje o licencji, prawach autorskich, wymaganiach sprzętowych, sposobie instalacji i uruchomienia, krótkim opisie oprogramowania. Nazwa sugeruje, że mamy go przeczytać przed próbą uruchomienia oprogramowania. W erze GitHub’a pliki README stały się wizytówkami wielu projektów, zawierają odnośniki do zrzutów ekranu, celach projektu, sposobie współpracy i czy nawet informacje o tym czy aktualna wersja przechodzi automatyczne testy. Co jednak najważniejsze, jest formą dokumentacji.
Dokumentacja jest ważna…
…i każdemu kto spędził z dowolnym kodem skomplikowanym choćby minimalnie bardziej niż „Hello world!” nie trzeba tego tłumaczyć. Mimo tego chciałbym podać parę powodów dla których warto pisać dokumentację:
- Za parę miesięcy może się okazać że musimy zmodyfikować kod choćby o dwa znaki i musisz wiedzieć w którym pliku, w której linijce to zrobić.
- Twój kod będzie lepszy. Przejrzysty, czytelniejszy, bo myślisz nad jego ułożeniem, „dizajnem” już wtrakcie pisania dokumentacji a nie wtrakcie pisania kodu.
- Jeśli dzielisz się kodem z kimkolwiek, ten ktoś chce z niego korzystać, żeby móc to robić musi wiedzieć jak i czy to właśnie z twojego kodu powinien.
- Im więcej dokumentacji piszesz, tym prostsze się to staje. A jeśli chcesz podjąć pracę przy jakimkolwiek poważniejszym projekcie, będzie Ci ciężko bez tej umiejętności.
No dobra ale co mam dokumentować skoro jeszcze nie napisałem kodu, a README mam pisać jako pierwsze?
Cały czas piszę o udokumentowaniu napisanego kodu, jednak celem tego tekstu jest tak naprawdę zachęcenie do napisania (bardzo nie wymagającej) specyfikacji jako pierwszej. Spełniającej jednocześniej funkcję dokumentacji.
Co to specyfikacja?
Specyfikacja mówi o tym jak ma działać kod, jakie wymagania ma spełniać. Może opisywać na przykład co wkładamy do jednej funkcji i co ma ona zwrócić, ale nie jest implementacją.
Bardzo ciekawym przykładem ukazującym co pozwala osiągnąć specyfikacja jest (z lekkim przymróżeniem oka) 
międzynarodowa stacja kosmiczna.
A konkretniej chciałbym pokazać tu piękną wizualizację stacji rozłożonej na moduły. 
Prawie żaden z tych modułów nie miał próbnego podpięcia do reszty stacji na ziemii, ale każdy z nich został zbudowany zgodnie ze specyfikacją. Pierwsze sprawdzenie czy moduły pasują do siebie odbywało się przy prędkości ~7,7 kilometrów na sekundę ~400 kilometrów nad naszymi głowami.
I wiecie co? Wszystkie pasowały idealnie, dlatego że każdy milimetr stacji jest dokładnie udokumentowany i zaprojektowany zgodnie ze specyfikacją.
Wracając na ziemię…
(niestety…)
Napisanie nawet najprostszej specyfikacji dla dużej biblioteki czy prostego skryptu pozwoli na zdefiniowanie jasno, przejrzyście i obiektywnie czego oczekujemy od kodu, bo nasze wyobrażenie będziemy musieli „przelać na papier”, „ubrać w słowa”, a te mają takie samo (bądź bardzo podobne) znaczenie dla każdego z nas w przeciwieństwie do mglistego zarysu w naszej głowie.
Dla bardzo ogólnego przykładu
Budzik
Ma pokazywać aktualną godzinę oraz odtwarzać zwracający uwagę dźwięk o określonych godzinach.
Funkcje:
- Pokazuje aktualną godzinę i minutę
- Alarm - Odtwarza denerwujący dźwięk o określonej godzinie
- Alarm - Pozwala na ustalenie godziny alarmu
- Alarm - Można wyłączyć bądź włączyć
- Pozwala na zmianę formatu wyświetlania pomiędzy 24 a 12 godzinnym
- Odtworzenie dźwięku o godzinie 12:00
Alarm:
- Jeśli godzina jest równa zapisanej oraz alarm jest włączony to odtwórz dźwięk
- Jeśli alarm jest wyłączony bądź godziny różnią się nic nie rób.
Sposób ustawiania godziny i godziny alarmu:
- Pokrętło zmieniające godzinę
- Pokrętło zmieniające minuty
- Przełącznik przełączający pomiędzy trybem nastawiania godziny a godziny alarmu
- Przełącznik włączający/wyłączający alarm
- Przełącznik włączający/wyłączający format godziny
Pomysły na przyszłość:
- Możliwość wyłączenia alarmu
- Zdalne wyłączanie alarmu?
Już z tej krótkiej notatki wiemy dokładnie co musimy napisać, musimy mieć możliwość wyświetlania godziny, zapamiętywania godziny alarmu, potrzebujemy 4 wejścia od użytkownika i możliwość odtwarzania dźwięku.
Tak napisana specyfikacja, jeśli będziemy się jej trzymać, stanie się automatycznie bardzo prostą dokumentacją, wystarczy, że po napisaniu kodu dodamy na przykład nazwy funkcji odpowiedzialnych za podane w jej treści założenia.
Nie jest to oczywiście substytut prawdziwej dokumentacji czy specyfikacji, jednak w każdym wypadku jest przydatną informacją. Nie będziemy przecież pisać 30 stronnicowej encyklopedii dla prostego skryptu ściągającego wiadomości z reddita, z drugiej strony nawet pisząc wielgachną bibliotekę przekształceń graficznych po przeczytaniu takiego pliku znamy zamysł autora jaką funkcję ma dana biblioteka i jakie zadanie spełnia.