1. Zasady technicznej organizacji
projektów programistycznych
Jarosław Rzeszótko // jrzeszotko@gmail.com
Tutoria GmbH
Styczeń 2015
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

2. Programowanie jest łatwe
O ile jedynym wymaganiem jest ”to ma działać”, to dzięki dostępności:
wygodnych języków programowania wysokiego poziomu
zintegrowanych środowisk programistycznych
wielkiej ilości gotowych bibliotek programistycznych
błyskawicznej i łatwej do otrzymania zewnętrznej pomocy (StackOverflow itp.)
programowanie jest naprawdę łatwe!
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

3. Programowanie jest trudne
Problemy pojawiają się wraz z:
Ewolucją modelu biznesowego i wymagań
Postępującą w czasie rozbudową projektu i akumulacją kodu
Wzrostem popularności projektu i co za tym idzie liczby użytkowników
Rozrostem zespołu programistycznego
Rozrostem infrastruktury
(liczby serwerów, liczby krajów w jakiej działa projekt, itp.)
Nieuchronną w perspektywie paru lat rotacją członków zespołu
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

4. Programowanie jest trudne
W wyniku działnia tych czynników, prawie każdy projekt programistyczny napotyka
pewne podstawowe problemy:
Pogmatwanie fundamentalnej logiki biznesowej
Stale rosnący czas potrzebny na wykonywanie bieżących zmian
Stale rosnący czas potrzebny na wdrożenia nowo zatrudnianych
programistów/programistek
Rosnącą liczbę błędów
Częste awarie
Wolne i niestabilne działanie aplikacji pod obciążeniem
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

5. Czym jest techniczna organizacja projektu?
Przez techniczną organizację projektu rozumiem działanie mające na celu optymalizacje
jego jakości od strony inżynieryjnej, to jest sumy poniższych jego cech:
Poprawności i zgodności z wymaganiami
Niezawodności
Wydajności
Przejrzystości dla osób dotychczas niezwiązanych z projektem
Łącznego długoterminowego kosztu
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

6. Czym jest techniczna organizacja projektu?
Techniczna organizacja projektu odbywa się w obliczu ograniczonych zasobów
czasowych, finansowych oraz ludzkich
Wobec tego nie chcemy ściśle rzecz biorąc jedynie podnosić jakości inżynieryjnej
w jakikolwiek sposób
Chcemy dokonywać jej ciągłej ”metaoptymalizacji”, to jest:
Identyfikować czynniki, które mają na nią w danej chwili największy pozytywny lub
negatywny wpływ
Znajdować konkretne sposoby na optymalizację tych czynników
Wdrażać te sposoby poczynając od tych które dają największe ogólne zyski w stosunku
do wysiłku ich wdrożenia
Ta prezentacja jest próbą identyfikacji kilku takich właśnie ważnych czynników,
które wydają się być wspólne dla wielu projektów
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

7. Przywiązuj wagę do czytelnego układu katalogów
Układ katalogów jest najbardziej podstawową metodą komunikacji podziału całego
systemu na niezależne moduły
Chaotyczny układ katalogów praktycznie uniemożliwia zrozumienie
wysokopoziomowej architektury systemu, a w zasadzie często oznacza jej brak
Dobre drzewo katalogów nie jest ani zbyt głębokie (zbyt wiele poziomów
zagnieżdżenia), ani zbyt szerokie (zbyt wiele plików w jednym katalogu)
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

8. Mądrze zarządzaj zależnościami
Automatyzuj zarządzanie zależnościami
Pieczołowicie dokumentuj zależności
Gdzie są używane
Jeśli ustawiona jest konkretna wersja, dlaczego?
Linkuj powiązane zgłoszenia na GitHub, pull requesty, itp.
Unikaj jak ognia modyfikowania zewnętrznych zależności przez monkey patching lub
przez włączenie zależności w główne repozytorium
Zamiast tego zgłaszaj błędy i pull requesty w orginalnym projekcie
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

9. Mądrze zarządzaj zależnościami
Słaby Gemfile:
gem 'rails', '3.0.18'
gem 'capistrano'
gem 'eventmachine', '1.0.0.beta.3'
gem 'will_paginate', '3.0.pre2'
gem 'daemons', '1.1.4'
gem 'gabba', :path => './vendor/gems/gabba'
gem 'browser', :path => './vendor/gems/browser'
gem 'calendar_date_select',
:git => 'git://github.com/paneq/calendar_date_select',
:branch => 'rails3test'
...
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

10. Mądrze zarządzaj zależnościami
Dobry Gemfile:
# Geocoding
gem 'geocoder'
# PDF documents generation (for receipts, for example)
gem 'prawn'
gem 'prawn-table'
# Excel documents generation (statistical reports, etc.)
gem 'spreadsheet'
# Trigger Google Analytics events from server side
# Switch back to upstream after 0.0.5 is released
gem 'staccato', git: 'git://github.com/tpitale/staccato'
# DelayedJob
gem 'delayed_job'
# Revert to upstream after 4.0.3 release:
# https://github.com/collectiveidea/delayed_job_active_record/issues/99
gem 'delayed_job_active_record',
github: 'collectiveidea/delayed_job_active_record'
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

11. Minimalizuj infrastrukturę
Więcej klocków - bardziej profesjonalna architektura? Nie!
Działa wolno, potrzebny nowy klocek? Rzadko! Co zmierzyłeś?
Każdy nowy komponent infrastruktury: baza danych, serwer proxy, cache, ... to
większe prawdopodobieństwo awarii.
To także konieczność zorganizowania i utrzymywania:
Monitorowania i narzędzi pomiarowych
Backupu
Failover-u
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

12. Maksymalizuj wykorzystanie istniejącej infrastruktury
Tymczasem, niektóre popularne komponenty infrastruktury oferują bogate, rzadko
wykorzystywane możliwości
Na przykład, w zakresie funkcji PostgreSQL oferuje:
Silnik wyszukiwania pełno tekstowego (tsearch)
Bazę płaskich dokumentów o wydajności porównywalnej do MongoDB (hstore)
Indeksowane zapytania na dokumentach JSON (typ jsonb)
Indeksowane zapytania geograficzne (moduły cube, earthdistance, PostGIS)
Funkcje kryptograficzne (moduł pgcrypto)
...
Wszystko to w ramach jednego procesu, wspólnego monitorowania, backup-u i
failover-u, z tymi samymi metodami wykonywania pomiarów i tak dalej
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

13. Nie twórz własnej infrastruktury
Jeżeli uważasz, że w ramach komercyjnego projektu świetnym pomysłem będzie
rozwinięcie własnej:
bazy danych
serwera www
systemu kryptograficznego
...
to prawdopodobnie jesteś w bardzo dużym błędzie
Jak to się kończy?
http://www.anton-pirker.at/the-big-rewrite-war-story/
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

14. Nie twórz własnej infrastruktury
Udane projekty w tej przestrzeni są wynikiem:
Wieloletniej pracy dziesiątków, często setek ludzi
Biegłej znajomości teorii podlegającej danemu zastosowaniu
Tysięcy popełnionych i naprawionych błędów
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

15. Nie twórz własnej infrastruktury
Jeśli naprawdę jesteś przekonana/przekonany, że masz świetny pomysł, to:
Wydziel osobne repozytorium
Zaprogramuj swój pomysł
Dokładnie udokumentuj przynajmniej cały zewnętrzny interfejs tego programu
Udostępnij projekt jako Open Source
Przekonaj trzy niepodległe Ci osoby do jego używania
Przekonaj się, że nikt nie chcę tego używać
Usuń to repozytorium i ogarnij się
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

16. Znaj wartość pisemnej dokumentacji
O skomplikowanych procesach i systemach po prostu nie da się z dobrym skutkiem
wyłącznie rozmawiać
Ważne systemy, komponenty, procedury i standardy które nie zostały pisemnie
wyspecyfikowane, nie są też raczej wysokiej jakości
Praca domowa:
Znajdź trzy ważne, często używane metody w swoim projekcie
Napisz do każdej z nich dokumentacje np. na wzór dokumentacji API Rails
Czy nie nasuwa Ci się wiele pomysłów na usprawnienia?
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

17. Znaj wartość pisemnej dokumentacji
Patrz też:
Matematyka, fizyka i inżynieria
Leslie Lamport, “Thinking for programmers”
https://www.youtube.com/watch?v=4nhFqf_46ZQ
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

18. Identyfikuj i dokumentuj “fundamenty” projektu
Jedynym z podstawowych warunków udanej pracy zespołowej jest obecność
dokumentacji najważniejszych:
Serwerów i systemów
Komponentów programistycznych
Procedur (korzystania z kontroli wersji, code review, zgłasznia propozycji zmian)
Standardów (dla wszystkich używanych technologii)
Jest to jedyny sposób upewnienia się, że cały zespół posiada:
Wspólne, pełne zrozumienie najbardziej podstawowych aspektów całego projektu
Jednolite, systematyczne i efektywne podejście do pracy
http://c2.com/cgi/wiki?ConceptualIntegrity
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

19. Pisz czytelną dokumentację
Stosuj zdania
Wszyscy wielcy pisarze je stosowali...
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

20. Pisz czytelną dokumentację
Unikaj “ściany tekstu”
Długie paragrafy ciągłego tekstu będą po prostu ignorowane
Pisz krótkie, zrozumiałe zdania...
... ale nie stosuj skrótów innych niż najbardziej powszechnie znane
Kiedy usunięcie któregokolwiek ze słów z któregokolwiek ze zdań wypacza jego sens
lub czyni je niegramatycznym, osiągnąłeś cel
Patrz też:
Strunk & White, “The elements of style”
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

21. Pisz czytelną dokumentację
Myśl o swoim docelowym odbiorcy
Decelowy odbiorca Twojej dokumentacji posiada oczywiście mniej informacji na temat
o którym piszesz, niż Ty
Pisanie dokumentacji która nie jest odbierana jako wyrwana z kontekstu wymaga
świadomego wysiłku
Nie pisz w pośpiechu i staraj się tłumaczyć “od początku” ...
... zwłaszcza jeśli zgłaszasz błąd w zewnętrznym projekcie
Ilustruj każde ogólne sformułowanie przynajmniej jednym konkretnym przykładem
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

22. Pisz czytelną dokumentację
Nadaj tekstowi klarowną strukturę wizualną
Dokumenty techniczne częściej są przeglądane niż czytane od początku do końca
Naprzemienne czytanie kodu i zwięzłego tekstu o wyraźnej strukturze, jest znacznie
łatwiejsze niż czytanie kodu na przemian z jednostajną, “powieściowej” prozą
Stwórz wyraźną hierarchię: nagłówki, podnagłówki, sekcje, paragrafy, przykłady
Używaj list wypunktowanych do wyliczeń, tabel i wykresów do prezentowania danych
Znaj możliwości swoich narzędzi:
W wiki, trackerach itp. stosuj podświetlanie składni, zwijane bloki kodu itp.
W kodzie korzystaj z możliwości RDoc
Niech to jakoś wygląda!
Patrz też:
“Grid Systems in Graphic Design”, Josef Müller-Brockmann
“Elementarz stylu w typografii”, Robert Bringhurst
“Detal w typografii”, Jost Hochuli
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

23. Klarownie organizuj dokumentację
Podstawowe dokumenty zorganizuj w Wiki, w formie drzewa, na przykład:
Standardy programistyczne
Ogólne zasady
Kod w Ruby
Modele Rails
Kontrollery Rails
Widoki Rails
SQL
HTML/CSS
...
Procesy
Kontrola wersji
Aktualizowanie serwerów
...
Przewodniki
Korzystanie z Git
Pisanie wydajnego kodu
Zgłaszanie zmian do istniejących Gemów
Tworzenie Gemów
...
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

24. Klarownie organizuj dokumentację
Dokumentacja mocno powiązana z kodem źródłowym powinna być częścią
repozytorium
Dotyczy to dokumentacji m. in.:
Układu katalogów
API dla najważniejszych obszarów logiki biznesowej
API dla najczęściej używanych komponentów ogólnego przeznaczenia
...
https://github.com/voloko/sdoc
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

25. Twórz standardy dla wszystkich używanych języków
W dłuższym horyzoncie czasowym brak standaryzacji dla jakiejkolwiek technologii
prędzej czy później powoduje poważne problemy.
Podstawę może stanowić któryś z istniejących standardów:
https://github.com/narkoz/guides
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

26. Standaryzuj użycie kontroli wersji
Wrzucanie zmian w Git-a to nie jest jeszcze kontrola wersji
Sensowna kontrola wersji to:
Logicznie oddzielne zmiany w oddzielnych commitach
Dokładne, czytelne opisy commitów dokumentujące kontekst dla dokonanych zmian
Używanie właściwych branchów dla właściwych zmian
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

27. Edukuj (siebie i innych) w zakresie pracy zespołowej
Aby zespół programistyczny mógł tworzyć wysokiej jakości, spójne projekty, wszyscy
programiści muszą posiadać dwie podstawowe umiejętności:
Umiejętność przygotowania swojego kodu do użytku i rozbudowy przez inne osoby
Umiejętność analizy istniejącego kodu pod kątem jak najlepszego dopasowania
zamierzonych zmian do zamysłów oryginalnego autora tego kodu
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

28. Edukuj (siebie i innych) w zakresie pracy zespołowej
Bierz udział (i zachęcaj do brania udziału) w projektach Open Source
Udane wprowadzenie zmiany w którymś z dojrzałych, uznanych projektów
Open Source wymaga od programisty:
Konkretnego pomysłu i jasnego jego zakomunikowania
Lektury wskazówek dotyczących wprowadzania zmian (“Contributing guidelines”)
Sensownego podziału wprowadzanej zmiany na commity i dobrego ich
udokumentowania
Dostosowania swojego kodu do stylu projektu
Nabyte w ten sposób umiejętności są bezcenne również w komercyjnym projekcie
Udane zmiany na uznanych projektach Open Source stanowią wobec tego lepszą
reklamę programisty niż najpiękniejsze z CV
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

29. Ważne decyzje podejmuj metodycznie
Niejednokrotnie błędnie podjęta decyzja projektowa skutkuje miesiącami czy wręcz
latami zmarnowanego i zbędnego wysiłku implementacyjnego
Rozpoznanie kiedy mamy do podjęcia decyzje o tak dużych potencjalnych
konsekwencjach jest sztuką w samą sobie
Niestety często decyzje te, nawet jeśli zostały rozpoznane jako ważne, są
podejmowane na zasadzie:
“widzimisię”
“lubie bo znam” / ”nie lubie bo nie znam”
“lubie bo fajna składnia”
“kolega używał”
Jest to jedno z podstawowych źródeł problemów projektów programistycznych
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

30. Ważne decyzje podejmuj metodycznie
Następujące, przykładowe decyzje mają najczęściej daleko idące konsewkencje:
Wybór technologii programistycznych
Języka programowania
Bazy danych
Bibliotek
...
Wybór infrastruktury
Liczby serwerów
Rodzaju serwerów
Rozmieszczenia usług pomiędzy serwerami
...
Projekt wysokopoziomowej organizacji kodu
Układu katalogów, konwencji nazewniczych i używanych wzorców projektowych
Dokładnego kształtu najbardziej ogólnych i najczęściej używanych modułów
...
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

31. Ważne decyzje podejmuj metodycznie
Wszystkie ważne decyzje projektowe tego typu muszą być ugruntowane w:
Jasno i precyzyjnie sformułowanych wymaganiach
Wymagania które nie są od początku dokładnie znane, należy zastąpić wspólnie
dokonanymi oszacowaniami i przedziałami
Szacowanie to nie to samo co zgadywanie i myślenie życzeniowe
Wiedzy teoretycznej z zakresu informatyki, m. in.:
Algortymów
Architektury komputerów
Systemów operacyjnych
Systemów rozproszonych
Baz danych
...
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

32. Ważne decyzje podejmuj metodycznie
Wszystkie ważne decyzje projektowe muszą być ugruntowane w:
Praktycznym doświadczeniu w stosowaniu szerokiego wachlarza technologii
Prototypujcie!
Udanych istniejących wdrożeniach danego pomysłu czy technologii
Np. w projektach Open Source
Eksperymentach (metoda naukowa)
Hipoteza
Eksperyment
Pomiar
Statystyka!
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

33. Ważne decyzje podejmuj metodycznie
W procesie podejmowania decyzji powinny:
Brać udział conajmniej dwie osoby
Zostać udokumentowane i upublicznione:
Znane wymagania oraz oszacowania nieznanych czynników
Rozważone alternatywy, ich za i przeciw
Wykonane eksperymenty, prototypy i testy
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

34. Ważne decyzje podejmuj metodycznie
Argumentacja stojąca za ostateczną decyzją również powinna być jasno opisana,
upubliczniona i znana wszystkim członkom zespołu
Zespół musi być świadomy, że decyzja została podjęta racjonalnie, a nie
argumentem przez autorytet
Dokumentacja pozwala porównać późniejszy rzeczywisty obrót spraw z projektem i
stale usprawniać proces podejmowania decyzji
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

35. Ważne decyzje podejmuj metodycznie
Przykłady ilustrujące racjonalny proces projektowy w działaniu:
Propozycja dodania funkcji generowania bezpiecznych tokenów do ActiveRecord:
https://github.com/rails/rails/issues/16879
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

36. Ważne decyzje podejmuj metodycznie
Metodologia podejmowania decyzji i zgłaszania zmian, na którą zgodził sie zespół,
powinna sama w sobie również zostać udokumentowana
Przykłady:
https://wiki.postgresql.org/wiki/Submitting_a_Patch
https://wiki.postgresql.org/wiki/Reviewing_a_Patch
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

37. Mierz i rządź
Ucz się dokonywać pomiarów i porównywać różne podejścia i implementacje
John Carmack o równoległych implementacjach:
https://web.archive.org/web/20140719065227/http:
//www.altdev.co/2011/11/22/parallel-implementations/
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

38. Czerp inspiracje z udanych projektów
https://github.com/torvalds/linux/tree/master/Documentation/
development-process
https://github.com/torvalds/linux/blob/master/Documentation/
ManagementStyle
https://github.com/torvalds/subsurface/blob/master/README
(Sekcja “Contributing”)
https://wiki.postgresql.org/wiki/Development_information
http://guides.rubyonrails.org/contributing_to_ruby_on_rails.html
http://contribute.jquery.org/
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych

39. Praca
Zapraszamy do pracy z nami
Szukamy jednego programisty z min. 2 latami doświadczenia w Rails
Rails 4.2, Ruby 2.2, RSpec 3, PostgreSQL
55-65 złotych brutto za godzinę pracy (średnio 9 000 - 11 000 złotych miesięcznie)
mailto:jrzeszotko@gmail.com
Jarosław Rzeszótko // jrzeszotko@gmail.com Tutoria GmbH
Zasady technicznej organizacji projektów programistycznych