Jak śledzisz, jakie klasy i funkcje napisał Twój zespół?

43

Pracując nad kodem, mam do czynienia z wieloma takimi samymi wyzwaniami, jakie stawiają moi koledzy z zespołu, i napisałem kilka pomocnych funkcji i klas, a także one. Jeśli jest dobra komunikacja, usłyszę o czymś wspaniałym, co ktoś złożył, a sześć miesięcy później, gdy będę jej potrzebować, mogę ją zapamiętać i wywołać tę funkcję, oszczędzając sobie czas. Jeśli tego nie pamiętam lub nigdy o tym nie wiedziałem, prawdopodobnie ponownie wymyślę koło.

Czy istnieje jakaś szczególna praktyka dokumentowania tego rodzaju rzeczy? Jak możesz je łatwo znaleźć?

Jeśli twój zespół nie ma takiej dokumentacji, jak dowiesz się, czy twoje koło już istnieje?

EDYTOWAĆ:

Wszystkie dotychczasowe odpowiedzi oprócz jednej dotyczą idealnej sytuacji, więc podsumuję te rozwiązania: dokumentacja i komunikacja; Wiki, spotkania stand-up itp. To są wspaniałe rzeczy, ale polegają na tym, że programiści mają czas (i umiejętności), aby napisać dokumentację i uczestniczyć w spotkaniach oraz robić notatki i wszystko pamiętać.

Najpopularniejsza jak dotąd odpowiedź (Caleba) jest jedyną, z której może skorzystać programista, który nie jest w stanie dokumentować i spotykać się i robi tylko jedno: programowanie. Programowanie jest tym, co robi programista, i tak, świetny programista może pisać dokumentację, testy jednostkowe itp., Ale spójrzmy prawdzie w oczy - większość z nas woli programowanie od dokumentacji. Jego rozwiązanie polega na tym, że programista rozpoznaje kod wielokrotnego użytku i wyciąga go do swojej własnej klasy lub repozytorium lub cokolwiek innego, a dzięki temu, że jest izolowany, staje się możliwy do znalezienia i ułatwia krzywą uczenia się do jego używania ... i zostało to osiągnięte poprzez programowanie.

W pewien sposób widzę to tak: właśnie napisałem trzy funkcje i przyszło mi do głowy, że ktoś inny powinien o nich wiedzieć. Mógłbym je udokumentować, napisać, ogłosić na spotkaniu itp. - co mogę zrobić, ale to nie jest moja siła - lub .... Mogę wyodrębnić je na zajęcia, nazwać to dobrze, sprawić, by działały jak czarną skrzynkę i przyklej ją tam, gdzie idą inne pliki klas. Następnie krótki e-mail z informacją, że jest łatwy. Inni programiści mogą zeskanować kod i zrozumieć go lepiej, niż mogliby izolować funkcję używaną w kodzie, którego nie do końca rozumieją - kontekst ten został usunięty.

Lubię to, ponieważ oznacza to, że posiadanie zestawu dobrze nazwanych plików klas z dobrze nazwanymi metodami jest dobrym rozwiązaniem, które można osiągnąć poprzez dobre programowanie. Nie wymaga spotkań i łagodzi potrzebę szczegółowej dokumentacji.

Czy są jeszcze jakieś pomysły w tym stylu ... dla izolowanych i obciążonych czasem programistów?

changokun
źródło
5
Chciałbym rozszerzyć pytanie, aby zadać pytanie na większą skalę, być może w firmie ponad 100 pracowników, jak to zrobić. Jakie najlepsze praktyki można zrobić, aby uniknąć powielania wcześniej wykonanej pracy?
Asaf
1
@Asaf - Podejrzewam, że poprawna odpowiedź będzie zależeć od liczebności populacji - to, co działa w sklepie dla 5 osób, nie będzie działać dla 50, a to, co działa dla 50, nie będzie działać dla 500. Odpowiedzi dla wszystkich byłyby mile widziane.
Dan Pichelman
3
To świetne pytanie!
Rocklan
4
Prawo Conwaya : „organizacje, które projektują systemy… są zobowiązane do tworzenia projektów będących kopiami struktur komunikacyjnych tych organizacji”.
Mark Rushakoff
2
@nathanhayfield: jest to rozwiązanie, które może działać dla 1 dewelopera, a do pewnego stopnia dla 2, ale nie dla 20 lub 100. I nawet gdy pracuję sam, wolę tematycznie rozdzielać funkcje pomocnika.
Doc Brown

Odpowiedzi:

29

Biblioteki. Ramy. Kontrola wersji.

Jeśli masz kod wielokrotnego użytku, ostatnią rzeczą, jakiej chcesz, jest to, aby różni członkowie zespołu skopiowali kod źródłowy do swojego projektu. Jeśli to zrobią, są szanse, że trochę się tutaj zmienią i poprawią, a wkrótce masz dziesiątki funkcji lub metod, które wszystkie mają tę samą nazwę, ale każda z nich działa nieco inaczej. Lub, być może bardziej prawdopodobne, oryginalny autor będzie nadal poprawiał kod, aby naprawić błędy, zwiększyć jego wydajność lub dodać funkcje, ale skopiowany kod nigdy nie zostanie zaktualizowany. Techniczna nazwa tego to wielki cholerny bałagan .

Właściwym rozwiązaniem jest wyciągnięcie rzeczy wielokrotnego użytku z dowolnego projektu, dla którego je zbudowałeś, i umieszczenie ich w bibliotece lub frameworku we własnym repozytorium kontroli wersji. Ułatwia to znalezienie, ale także odradza wprowadzanie zmian bez uwzględnienia wszystkich innych projektów, które mogą z niego korzystać. Możesz rozważyć posiadanie kilku różnych bibliotek: jednej dla dobrze przetestowanego kodu, który prawdopodobnie już się nie zmieni, jednej dla rzeczy, które wydają się stabilne, ale które nie zostały dokładnie przetestowane i sprawdzone, drugiej dla proponowanych dodatków.

Caleb
źródło
5
Chciałbym również polecić bardzo dokładny zestaw testów regresji dla biblioteki wielokrotnego użytku. Nawet jeśli zmiana wydaje się nieszkodliwa, ktoś może być zależny od tego zachowania.
Bobson
2
Myślałem, że terminem technicznym jest BBOM .
zzzzBov
2
Twoja odpowiedź na pierwszy rzut oka brzmi rozsądnie, i to w mniejszej lub średniej skali, ale widziałem również ciemną stronę dyrektywy „nie kopiuj”. Jeśli masz różne zespoły dla różnych produktów, z różnymi warunkami licencji, różnymi cyklami życia i różnymi umowami serwisowymi, ostatnią rzeczą, jakiej chcesz, jest połączenie różnych produktów z własną biblioteką fragmentów kodu, które nie spełniają tych wymagań konserwacyjnych . Biblioteki dla tego rodzaju scenariusza muszą mieć bardzo wysoką jakość, a czasem jeszcze bardziej efektywne jest, aby zespół skopiował kod i ...
Doc Brown
3
@Caleb: zachowaj spokój, przeczytaj całkowicie mój post. Chodzi mi o to: kopiowanie kodu z innego miejsca, poprawianie go i integrowanie z biblioteką zespołów niekoniecznie prowadzi cię na „drogę do zatracenia”. Jeśli masz dwie biblioteki z nakładającymi się funkcjami i dwa zespoły, z których każdy jest odpowiedzialny za utrzymanie swojej biblioteki, sytuacja nie jest taka zła. To nie jest idealne, ponieważ jeden zespół może wykonać trochę pracy, a drugi też, ale czasami przewaga nad utrzymaniem niezależności przez te zespoły przeważa nad podwójną pracą.
Doc Brown
1
@DocBrown Tam sytuacje, w których konieczne staje się skopiować kod, ale to powinno być świadoma decyzja, a nie coś, że jesteś zmuszony do zrobienia ze względu na sposób, w jaki kod został dzielonego w pierwszej kolejności.
Caleb
13

Jednym z rozwiązań jest założenie Wiki w tym celu i napisanie dokumentów wysokiego poziomu na temat posiadanych komponentów wielokrotnego użytku, sposobu rozwiązania problemu itp.

Trudność polega na tym, aby każdy w twoim zespole stale utrzymywał Wiki. Ale każda inna dokumentacja cierpi z powodu tego samego problemu.

Część twojego kodu może być również wystarczająco dobra, aby umieścić go w bibliotece wielokrotnego użytku. Dzięki temu łatwiej jest później znaleźć kod.

Doktor Brown
źródło
5
Wiki nie jest właściwym sposobem rozpowszechniania kodu. To świetny sposób na komunikowanie się o kodzie, ale (patrz moja odpowiedź) nie chcesz, aby ludzie kopiowali coś większego niż fragment kodu z wiki i wklejali go do swojego projektu.
Caleb
@Caleb komunikacja jest trudna
jk.
@jk - Problemy z komunikacją są skomplikowane, jeśli nie masz kontroli źródła, o której mowa w C
JeffO
3
@Caleb: pytanie OP nie dotyczyło rozpowszechniania kodu, chodziło o komunikację i znalezienie go później.
Doc Brown
@DocBrown Znowu strony wiki świetnie się komunikują i zapewne dlatego narzędzia takie jak GitHub mają takie wbudowane. Ale łatwym do znalezienia kodem nie jest to, że jest wspomniane na wiki, ale jest przechowywane w znanym miejscu. To może być wiki, ale jeśli mówimy o kodzie, którego ludzie faktycznie użyją (w porównaniu z fragmentem ilustrującym rozwiązanie), powinna to być biblioteka, coś, co można zbudować, przetestować i które można włączyć bez pomnożenia liczby miejsc, w których prędzej czy później trzeba będzie je zaktualizować.
Caleb
7

Będąc w firmie zatrudniającej 700 pracowników, w zespołach od 2 do 20 osób, oto moje doświadczenie.

Na poziomie zespołu

Codziennie odbywamy „spotkania standupowe” przez około 15-20 minut. Możemy szybko podzielić się powszechną wiedzą, taką jak: „Zrobiłem tę funkcję wczoraj, to tak mocno kołysze”.

Mamy również wiki na projekt. Co oznacza, że ​​możemy udostępniać (techniczne) informacje o tym, co zostało zrobione w projekcie, w tym wbudowane niestandardowe klasy / funkcje.

Na poziomie agencji

Na poziomie agencji mamy 4 narzędzia:

  • Kolejna wiki. Ma to głównie na celu dostarczenie nam informacji o sprzęcie i innych rzeczach, ale czasami używamy ich do dzielenia się informacjami technicznymi do przejrzenia przed umieszczeniem ich na poziomie firmy.
  • Cotygodniowe spotkania Mają przede wszystkim znać postępy każdego zespołu / projektu, ale ponieważ jesteśmy głównie entuzjastami technologii, możemy przynieść fajne rzeczy.
  • Lista mailingowa. Mamy korespondencję ze wszystkimi w agencji. Dostaje się tam mnóstwo fajnych rzeczy / zabawnych rzeczy / przydatnych rzeczy.
  • Repozytorium VCS. Każda agencja ma swoje osobiste repozytorium, w którym mamy małe projekty, głównie moduły, których używamy w różnych projektach.

Na poziomie firmy

Na poziomie firmy jest bardziej zorganizowany.

Wiki „na poziomie agencji” jest w rzeczywistości częścią wiki firmy.

Wiki jest następnie dzielone na podstawie technologii. W ten sposób każdy może go ulepszyć, przeszukać go i w zasadzie ożywić wiki.

Dostępne są również listy mailingowe, które możemy subskrybować. Każdy w agencji może się subskrybować, a większość ludzi korzysta z co najmniej jednej lub dwóch technologii, w rzeczywistości większość ludzi obserwuje 5-10 z nich.

A VCS jest oczywiście najlepszym systemem współdzielenia kodu.

Wniosek

Podsumowując, nie ma jednoznacznego rozwiązania. Dzielenie się wiedzą zawsze było dużym problemem i prawdopodobnie pozostanie. Istnieje wiele rozwiązań do tworzenia baz wiedzy i prawdopodobnie można by dopasować swój rachunek. Jednak niektórzy ludzie próbują uzyskać jeszcze lepszą KB, ponieważ obecne rozwiązania nie zawsze są bardzo inteligentne.

Florian Margaine
źródło
Uważam, że wniosek nie powinien zawierać nic więcej niż „wiki, wiki, wiki, wiki, wiki”, ale poważnie, dobra odpowiedź, wewnętrzna wiki może być dobra do opisywania szczegółów wyższego poziomu lub wieku użytkowania, nie wspominając już o możliwość wyszukiwania to dobra oszczędność czasu.
RhysW
6

Wszystko sprowadza się do komunikacji.

Wiki są świetne i zdecydowanie powinieneś je zainstalować i używać. Dobry wewnętrzny intranet dla programistów jest dobry, jeśli ludzie go przeczytają i zaktualizują, więc naprawdę mówisz o problemie z ludźmi. Możesz zasugerować cotygodniowe spotkania „aktualizacji zespołu”, podczas których wszyscy się spotykają i przedstawiają przegląd prac. Liderzy technologii (przynajmniej!) Powinni się spotykać i rozmawiać o tym, co robi każda drużyna. Nieformalne sesje „Brązowej torby” są świetne, zaplanuj je w porze lunchu i zachęć ludzi do rozmowy.

Potrzebujesz także sposobu udostępniania kodu, pakowania go, wersjonowania i dystrybucji. Byłoby łatwiej, gdybyś miał naprawdę dobrze zarządzane repozytorium kodu źródłowego, dobrze ułożone w folderach „wspólnych” i projektowych.

Jeśli nic takiego się nie dzieje, porozmawiaj o tym z szefem, wyjaśnij, w jaki sposób przyniesie to korzyść firmie, i zasugeruj dalszą drogę :)

Rocklan
źródło
1
Chciałbym przesunąć „wspólną” koncepcję nieco dalej w twojej odpowiedzi.
JeffO
4

Sesje przeglądu kodu mogą pomóc. Jeśli Twój zespół spotyka się regularnie w celu omówienia opracowanych rozwiązań, osoba, która opracowała rozwiązanie, może pokazać innym, jak z niego korzystać. Jeśli ktoś poruszy kwestię, której się trzyma, inni członkowie zespołu mogą zaproponować podejście zwiększające ponowne wykorzystanie istniejących komponentów.

Daenyth
źródło
1
Potem 4 lata i 600 funkcji później, kiedy chcesz zapamiętać tę funkcję, która została stworzona przez jakiś czas? Część problemu OP polegała na próbie zapamiętania wszystkich rzeczy, które zostały stworzone, chociaż jest to dobre na początku, że nie utrzyma się przez okres może jednego lub dwóch miesięcy
RhysW
2

Najlepszym sposobem radzenia sobie z czymś takim jest posiadanie struktury repozytorium, która ma kilka prostych konwencji, dzięki czemu jako programista wiem, czy istnieje funkcja doXYZ, z grubsza, gdzie powinienem szukać tej funkcji. Niezależnie od tego, czy korzystasz z przestrzeni nazw, katalogów, modułów, wtyczek, pakietów, cokolwiek, kod powinien być modułowy, aby funkcje, które robią to samo lub uzyskiwały dostęp do tych samych źródeł danych, znajdowały się w większości w tym samym miejscu.

Jonathan Rich
źródło
0

Idealnie byłoby, gdyby przynajmniej jedna osoba oprócz autora dokonywała przeglądu kodu przy każdym zameldowaniu. Proces przeglądu kodu może pomóc w złagodzeniu problemu związanego z rejestrowaniem wielu zduplikowanych metod. Oczywiście ograniczają Cię wiedza recenzentów.

TL; DR: Recenzje kodu dla każdego zameldowania.

Carolyn
źródło
2
Nie rozumiem Czy zamierzasz wyrzucić przetestowany i działający kod tylko dlatego, że wygląda jak duplikat w przeglądzie kodu? Pytanie polegało przede wszystkim na tym, jak uniknąć pisania duplikatu kodu. Sesja taka jak odpowiedź @ daenyth wydaje się lepsza.
adrianm
Gdyby recenzent powiedział mi, że dodam kod, który powiela funkcjonalność, a ja sprawdziłem i stwierdziłem, że mają rację, do licha, zeskrobałbym ten kod. (Prawdopodobnie sprawdziłbym również, czy moja implementacja jest lepsza, a jeśli tak, zobaczę, czy mógłbym refaktoryzować inną implementację zamiast dodawać nową.)
Carolyn