Czy powinieneś napisać dobrą dokumentację i czysty kod, aby zwiększyć „współczynnik magistrali”?

Jednym z głównych celów firm zajmujących się tworzeniem oprogramowania jest zwiększenie ich współczynnika autobusu. Jest to również zalecane w rozmowie zorganizowanej przez Google .

Oznacza to, że powinieneś zakodować i udokumentować wszystko w taki sposób, że jeśli jutro wpadniesz na autobus, projekt może być kontynuowany. Innymi słowy, powinieneś dać się łatwo zastąpić innemu programistowi o podobnych umiejętnościach.

Wymienianie nie jest sprzeczne z interesem programisty? W książce 48 zasad władzy Reguła 11 stanowi, że powinieneś próbować uzależniać ludzi od ciebie, aby zdobyć władzę, co następnie przekłada się na nagrody pieniężne.

Poza scenariuszem, w którym potrzebujesz dokumentacji dla siebie, aby kontynuować projekt po 6 miesiącach przerwy, wydaje się, że istnieje wyraźny konflikt interesów między deweloperem a firmą programistyczną.

Jako programista powinieneś naprawdę napisać doskonałą dokumentację i czytelny kod dla wszystkich; czy też powinieneś napisać kod i dokumentację w taki sposób, aby spełniał zadanie i sam mógłbyś go zrozumieć, ale inna osoba może mieć problemy ze zrozumieniem?

Powinieneś dążyć do tego, aby stać się niezastąpionym, nie pisząc kodu, którego nikt nie rozumie, ale gromadząc więcej doświadczenia i wiedzy niż inni. Ten pierwszy sposób sprawia, że ​​jesteś programistą, z którym wszyscy starają się unikać pracy, ponieważ będą się bać i nie znosić pisania kodu. W ten drugi sposób możesz zostać poszukiwanym członkiem zespołu, którego menedżerowie chcą mieć w swoim zespole.

Z mojego doświadczenia wynika, że ​​pisanie czystego, dobrze udokumentowanego (a najlepiej samodokumentującego) kodu zawsze się opłacało. W rzeczywistości korzystałem z prawie każdej okazji, aby pomagać i uczyć innych (a także uczyć się od nich, kiedy wiedzieli coś lepszego) i prawie nigdy nie czułem zagrożenia, że ​​zostanę zastąpiony przez kogoś mniej zdolnego ode mnie. W rzeczywistości zwykle pomogło to całemu zespołowi w lepszej pracy i szybszym rozwiązywaniu problemów, co jest marzeniem każdego menedżera - a rozsądny menedżer nie chce zastępować członków dobrego zespołu.

Jeśli zamierzasz manipulować organizacjami lub ludźmi w sposób tak przejrzysty, lepiej byliby głupi lub w dżemie, który nie pozostawia im innego wyboru. Dobrze prowadzony sklep programistyczny sprawdziłby twój niejasny kod i brakującą dokumentację i po prostu zwolnił cię, zanim mógłbyś wyrządzić wiele szkód. Jeśli są źle zarządzani lub nie są w stanie zmusić innych programistów do pracy dla nich, dlaczego mielibyście mieć u nich zabezpieczenie?

PS Ani pan Greene, ani Machiavelli nie osiągnęli wiele poza pisaniem książek, które starały się schlebiać niedoszłym „twardym ludziom” tamtych czasów. Skorzystaj z ich porady z odrobiną soli.

Jeśli jesteś niezastąpiony, nie możesz awansować.

Nie chcesz być niezastąpiony. Nie chcesz, aby ludzie czuli się zależni od ciebie, chcesz, żeby cię docenili. Ogólnie rzecz biorąc, chcesz trzymać się z dala od ludzi, którzy uważają, że nawet połowa praw władzy powinna obowiązywać w relacjach (zawodowych lub osobistych).
Reguły te są instrukcją dotyczącą tego, jak skutecznie ustanowić sytuację, w której wygrywa-przegrywa. To, czego chcesz, to sytuacja korzystna dla obu stron.
Gdy tylko ludzie zaczną odczuwać, próbujesz odepchnąć ich od przegranej strony sytuacji wygrana-przegrana, będą walczyć. Próby ustalenia sytuacji wygrana-przegrana często kończą się przegraną, ponieważ efektywnie marnujesz zasoby na doprowadzenie partnera do utraty pozycji, zamiast inwestować je w ogólny sukces partnerstwa.

Jeśli zrobisz to ze swoimi pracodawcami, będą oni próbować narzucić ci środki, aby zmniejszyć monopol na twoją wiedzę. Przeważnie będą to absurdalne wytyczne dotyczące tego, jak musisz wykonywać swoją pracę, a tym samym zamienisz swoje życie zawodowe w piekło. Zadzwonią też o 3 w nocy, gdy coś się zepsuje, ponieważ jesteś jedyną osobą, która może to naprawić. Próba wykorzystania takich sytuacji, jak dźwignia, może przynieść odwrót i spowodować więcej problemów.

Cmentarze są pełne niezbędnych ludzi.
- Gaulle, Charles De

Więc wytnij gówno i wykonuj swoją pracę właściwie. Jeśli nie dla niczego innego, to dla ciebie, ponieważ prawdopodobnie będziesz biedną duszą, która musi wprowadzić pewne zmiany w kodzie za 2 lata.

Negatywne odpowiedzi nie są zbyt zaskakujące, biorąc pod uwagę liczbę lepszych niż przeciętni programistów, których przyciąga ta strona. Utalentowani ludzie na ogół nie muszą uciekać się do tego rodzaju taktyk bezpieczeństwa poprzez zaciemnianie. Ale pracowałem u dostawcy motoryzacyjnego z listy Fortune 500 z kilkoma niezbyt utalentowanymi programistami, którzy sami dla siebie stworzyli małe lenna, których gorliwie strzegli, tworząc mnóstwo dokumentacji dla przerażających interfejsów, które zaprojektowali.

Całe zadanie jednego faceta polegało na utrzymywaniu kodu modułu, który zmostkował dwa całkowicie oddzielne podsystemy, umożliwiając modułom w każdym systemie komunikację za pośrednictwem UART. Zasadniczo był to Serial Programming 101. Zamiast po prostu stworzyć ogólny interfejs, który wyglądałby mniej więcej tak:

  int sendData (int targetModule, void * data, size_t byteCount);
  int recvData (int sourceModule, void * data, size_t maxBytes);

stworzył osobne kody dla każdej wiadomości, którą dowolne dwa komunikujące się moduły mogłyby chcieć wysłać sobie nawzajem. Co oznaczało, że jego moduł musiał wiedzieć o każdej wiadomości i był aktualizowany za każdym razem, gdy wiadomość była dodawana lub zmieniana. Mów o niewłaściwej intymności!

Chodzi o to, że ten facet starannie prowadził dokument Word zawierający wszystkie kody operacyjne / wiadomości i odpowiednio go aktualizował. To stała się jego cała praca . Kilka razy w tygodniu wysyłał nową wersję do wszystkich nieszczęśliwych ludzi, którzy mieli go na swojej krytycznej ścieżce. I było to postrzegane jako „profesjonalne”, ponieważ zarząd uwielbiał widzieć dokumentację. W pewnym sensie płaczę dla przemysłu motoryzacyjnego.

Chyba o to mi chodzi: czasami pisanie dokumentacji może w rzeczywistości chronić przeciętnych programistów. Menedżerowie często nie potrafią odróżnić dobrego projektu od złego, a wielu jest zmuszonych do podejmowania decyzji technicznych przy ograniczonej ilości informacji. Jest to dla nich niezwykle stresujące. Widok dokumentu Word z dziesiątkami starannie sformatowanych tabel może być bardzo pocieszający - nawet jeśli to, co opisuje, jest zasadniczo złym pomysłem.

Wymienianie nie jest sprzeczne z interesem programisty?

Nie chcę ci tego łamać, ale wszyscy są wymienni. Jasne, czasami może to być niewielkie wyzwanie, aby cię zastąpić (jeśli jesteś wystarczająco doświadczony i bystry), ale lata świetlne od niemożliwego.

Sposobem, aby być naprawdę cennym towarem dla pracodawcy (nie tylko obecnego pracodawcy, ale każdego pracodawcy), jest wykazanie umiejętności pisania kodu tak łatwego do odczytania przez każdego, kto go czyta (krótki czas potrzebny na rozpoczęcie pracy) i dokumentowania kod (każdy może uzyskać ogólny przegląd twoich systemów bez konieczności zagłębiania się w kod).

Właściwie bycie dobrym w dokumentowaniu kodu jest trudną do zdobycia w dzisiejszych czasach, więc to samo pomoże odróżnić cię od innych.

Czysty i dobrze udokumentowany kod również zasługuje na wznowienie (przynajmniej namacalne wyniki, tj. „Byliśmy w stanie zaangażować nnowych programistów przy minimalnym przyspieszeniu i pomocy dzięki mojej dokumentacji), gdzie podstępnie podchodzimy do tworzenia „niezastąpiony” nie jest.

Wymienianie nie jest sprzeczne z interesem programisty?

Zależy, jakie są interesy tego programisty. Jeśli jesteś tym, który chce przetrwać w jednym zadaniu przez całą karierę, bądź całkowicie niezbędny dla firmy, która nagradza niekompetencję i zarabia dobre pieniądze, to tak, absolutnie.

Ale co się dzieje, gdy firma ulega awarii, prawdopodobnie dlatego, że zatrudniła zbyt wielu takich ludzi? Gdzie idziesz dalej? Co, gdy zapytają cię, dlaczego pozostawałeś w tej samej pracy przez 15 lat? I tak dalej.

Teraz spójrz na to inaczej: ilu programistów straciło pracę, będąc kimś, kto pisze kod, który każdy może przeczytać?

Jedynym prawdopodobieństwem takiego zdarzenia jest sytuacja, gdy firma ma kłopoty i zwalnia ludzi. Jeśli tak się dzieje, lepiej wyjdź i będziesz bardzo dobrze przygotowany na nadchodzące wywiady. Dodatkowo twoje sumienie będzie całkowicie darmowe - nie pozostawisz po sobie niewytłumaczalnego kodu, który napisałeś dla własnego zysku.

Nie wiem, jaką jesteś osobą, ale to lepiej służy moim zainteresowaniom.

Osobiście uważam, że jedną z moich największych zalet jest automatyzacja własnej pracy. Jak myślisz, co zwykle myśli firma, gdy stałem się nadwyżką moich własnych wymagań? Czy myślą, że „ok, pozbędziemy się go teraz”, czy też myślą, „dlaczego nie przeniesiemy go na inną rolę i nie pozwolimy mu zrobić tego ponownie”?

Wymienianie nie jest sprzeczne z interesem programisty?

Masz rację, ale myślę, że źle zrozumiałeś znaczenie zamiennika. Mogłem znaleźć 1000 programistów, którzy piszą gorączkowy kod, nieudokumentowany, który może szybko przekształcić się w niemożliwy do utrzymania bałagan.

Programiści, którzy produkują nie tylko stałe programy, ale także czysty kod, dokumentację informacyjną i zapewniają ciągłość projektu, który jest nie tylko niezastąpiony, ale bezcenny .

Odpowiem na to pytanie z innej perspektywy, ponieważ istnieje już kilka doskonałych odpowiedzi.

Zastanów się, co się dzieje, gdy grasz w małe gry, próbując uczynić siebie „niezastąpionym”, uniemożliwiając innym osobom nauczenie się, jak działa Twój kod. Pozostajesz w tym samym zadaniu, utrzymując własne bałagany, dopóki firma cię toleruje. I to jest najlepszy scenariusz, najgorszym scenariuszem jest to, że inni, bardziej utalentowani i bardziej etyczni inżynierowie i menedżerowie w twojej firmie dostrzegają przeszkodę, jaką narzucają ci złe praktyki, i postanawiają coś z tym zrobić: zwalniając cię i przepisując wszystko od zera. To zostało zrobione. W rzeczywistości zdarza się dość często.

Teraz zastanów się, co się stanie, gdy napiszesz dobry kod i dobrą dokumentację. Tworzysz komponent lub system, który działa dobrze, że po pewnym czasie działania błędy działają płynnie i nie trzeba na nie patrzeć. Utrzymanie go zajmuje niewiele wysiłku. Następnie możesz przejść do większych i lepszych projektów, z solidnym zwycięstwem pod swoim pasem. Ludzie rozpoznają cię za dobrą pracę i zaczną szanować twoją opinię. Będziesz mieć możliwość poruszania się w górę łańcucha żywnościowego i podejmowania bardziej znaczących decyzji, wykonywania ważniejszej i bardziej wpływowej pracy lub zarządzania projektami na wyższym poziomie. Twoja kariera się poprawi, dostaniesz awans, zarobisz więcej pieniędzy, zyskasz uznanie i aprobatę rówieśników, dodasz do sukcesów coraz ważniejszych projektów.

Którą trasę wolisz?

Jeśli jesteś pojedynczym punktem awarii, Twój klient (lub pracodawca) prawdopodobnie spróbuje cię zastąpić; zawsze jest punkt, w którym wymiana oprogramowania jest mniej kosztowna niż jego konserwacja, bez względu na to, jak ważne wydaje się to być. Jest powód, dla którego IT jest jednym z najbardziej zlecanych zawodów.

Z drugiej strony bycie wymiennym daje kilka bezcennych korzyści:

• móc wziąć urlop
• nie będąc na dyżurze
• wolność odejścia i pracy nad nowym i ekscytującym projektem

Jeśli nie poświęcisz 5 minut na napisanie szybkiej dokumentacji, spędzisz godzinę na ponownym czytaniu i wyjaśnianiu ludziom, kiedy będą musieli użyć twojego kodu.

Jeszcze gorzej może być spędzanie dni na szukaniu nowej pracy, ponieważ twój szef odkrył, że nie piszesz łatwego do utrzymania kodu.

Doskonała dokumentacja ostatecznie stanie się przestarzała przy refaktoryzacji / ewolucji, a jej aktualizowanie jest naprawdę czasochłonne.

Czysty kod + test jednostkowy> doskonała dokumentacja

Odpowiedź na twoje pytanie brzmi „tak”. Tak, powinieneś napisać dobrą dokumentację i czysty kod. Umyślne działanie w inny sposób pokazuje brak uczciwości, który, choć coraz bardziej rozpowszechniony w świecie biznesu, nie jest nagle „dobrą” rzeczą.

Nikt nie jest niezastąpiony. Ludzie, którzy produkują sytuację, w której uważają, że mają tendencję do trudnego odkrycia, że ​​tak nie jest. Wytworzenie współzależności dla siebie przynosi efekt przeciwny do zamierzonego, ponieważ ogranicza także ciebie, a nie tylko pracodawcę.

Jednym z głównych celów firm tworzących oprogramowanie jest zwiększenie współczynnika Bus

Fałszywa przesłanka. Głównymi celami firmy zajmującej się tworzeniem oprogramowania (w każdym razie, nad którą pracowałem) jest wytwarzanie najlepszego oprogramowania, jakie potrafią, i zarabianie pieniędzy, niekoniecznie w tej kolejności. Zmniejszenie „współczynnika autobusu” to tylko jeden ze sposobów uniknięcia utraty pieniędzy.

Artykuł 11 Naucz się utrzymywać ludzi na tobie.

Co to dla ciebie znaczy?

Czy chcesz, aby ludzie polegali na tobie, ponieważ podważyłeś ich w taki sposób, że mogą tylko iść naprzód z twoją pomocą? A może chcesz, aby ludzie polegali na tobie, ponieważ jesteś mądry i wnikliwy, niezawodny, godny zaufania i może pomagać innym w wykonywaniu ich zadań? Czy chcesz, aby Twoi koledzy wyglądali źle bez Twojej pomocy, czy chcesz, aby docenili Cię za to, że wyglądają dobrze?

To Twoja decyzja.

(przy założeniu kodu produkcyjnego)

Staram się iść trochę dalej. Pisałem o robieniu programów „idiotycznymi”, ale nie zawsze to kwalifikuję: piszę dużo kodu, którego inni ludzie nie zobaczą lub z którym nie będą pracować (przynajmniej takie są oczekiwania, kiedy zostaną napisane). jajestem idiotą, przed którym staram się obronić w tej sprawie. Dobrze jest, gdy Twój program wykrywa problemy, a problem został tak uproszczony, że oczywiste jest, że wystąpił błąd i jego pochodzenie. Prawda jest taka, że ​​szczegóły implementacji są oczywiste, gdy piszesz program (chyba że wdrażasz go przedwcześnie), ale powinny być abstrakcyjne i odporne na błędy dla klientów (nawet jeśli istnieje lokalizacja modułu). Powodem jest to, że programy stają się bardzo złożone. Czasami możesz rozdzielić problemy, ale nie przez cały czas. Jeśli trzymasz swoje komponenty bardzo surowe, proste, dobrze zamknięte i idiotyczne, zwykle dobrze się skalują, a większość wad wykrywa się przed ich wysłaniem. Łatwiej jest ponownie użyć, a Ty masz więcej pewności siebie i łatwiejszego ponownego użycia programów. te złożone programy, które piszesz, stają się bardziej złożone (nawet dla ciebie) po pewnym czasie nieobecności w programie. Gdy przeczytasz go w ciągu 6 miesięcy, zrozumienie i debugowanie może potrwać absurdalnie długo w porównaniu z wersją idiotyczną. Jeśli składnik wprowadza przełomową zmianę, w przeciwnym razie może pozostać niewykryty przez długi czas. Programy są złożone; nie możesz uciec od tej rzeczywistości, ale możesz uczynić ją idiotyczną dowodem, co znacznie ułatwi ci życie, gdy coś pójdzie nie tak lub gdy trzeba go ponownie wykorzystać lub zmienić. Dlatego podejście idiotyzmu oznacza, że ​​twoje oprogramowanie może być zrozumiane, ponownie użyte lub utrzymywane przez twoich juniorów lub osoby w zespole również (nie tylko kogoś tak dobrego / doświadczonego jak ty). Zastąpienie to osobny problem: jeśli ludzie uwielbiają pracować z twoimi programami, robisz dobrą robotę - nie martw się o wymianę. Jasne, mógłbym wymyślić scenariusze, w których niezrozumiałe programy mogłyby uratować twoją pracę, ale napisanie dobrego programu, z którego inni mogą korzystać i które jest utrzymywane, jest wyraźnie mniejszym złem (spójrz na odrodzenie się innych). Jeśli złapię się na pisaniu czegoś, co nie jest idiotycznym dowodem, staram się to naprawić.

Poza scenariuszem, w którym potrzebujesz dokumentacji dla siebie, aby kontynuować projekt po 6 miesiącach przerwy, wydaje się, że istnieje wyraźny konflikt interesów między deweloperem a firmą programistyczną.

Naprawdę nie masz pojęcia, co myślisz, kiedy wracasz do uśpionych implementacji. Kiedy jesteś naprawdę doświadczony, problem jest prostszy, ponieważ możesz polegać bardziej na ustalonych metodach lub podejściach, których używasz. To jednak zakłada również, że metody te są niezmienne. Mimo że dokumentacja może być luźna, nadal musisz być defensywny w swoich implementacjach (np. Wiesz, że w tym scenariuszu nie należy zdawać NULL - sprawdź ten warunek).

Jako programista powinieneś naprawdę napisać doskonałą dokumentację i czytelny kod dla wszystkich; czy też powinieneś napisać kod i dokumentację w taki sposób, aby spełniał zadanie i sam mógłbyś go zrozumieć, ale inna osoba może mieć problemy ze zrozumieniem?

Polecam idiotyczne podejście, które jest jeszcze jaśniejsze i bardziej odporne na błędy niż podejście oparte na współczynniku magistrali. Napisz swoje programy i dokumentację w taki sposób, aby były zrozumiałe dla osób spoza projektu - to też jest dobre dla ciebie. Takie postępowanie zwiększy twoją wartość dla twojej firmy i zespołu, nie będą chcieli cię zastąpić.

Zasadniczo źle zrozumiałeś grę. Ta gra nie polega na robieniu tych samych starych rzeczy, które robiłeś wcześniej, będąc odpowiedzialnym za cały napisany kod, ponieważ nikt go nie rozumie. Gra polega na ukończeniu projektu i przejściu do następnego, pozostawiając za sobą kod, który ktoś może łatwo zrozumieć i pracować pod twoją nieobecność, abyś mógł robić nowe rzeczy i podejmować coraz więcej różnych obowiązków. Twoje założenie działa tylko wtedy, gdy jesteś szczęśliwy, że utknąłeś w kółko, robiąc to samo, bez szansy na naukę lub poprawę.

Zwrócę też uwagę, że jeśli nie będziesz miał okazji często patrzeć na ten kod, ty również będziesz miał problem z jego zrozumieniem za sześć miesięcy, jeśli umyślnie go zaciemnisz.

I udokumentować co trochę kodu piszę, nie jest tak, że inni mogą go czytać, ale tak, że ja może go odczytać w ciągu 3 miesięcy czasu! Chodzi o ułatwienie konserwacji. Jeśli jesteś odpowiedzialny za napisany kod i nie możesz naprawić błędów, które pojawią się później, to będziesz chciał, aby było dobrze udokumentowane ... Nie ma znaczenia, jak możesz być wymienny, jeśli nie jesteś w stanie wykonać swoją pracę!

Każdy „niezastąpiony” profesjonalista komputerowy, z którym miałem nieszczęście wchodzić w interakcje, został zastąpiony, w dużej mierze dlatego, że starali się utrzymać zakładników w swoich zasobach. Kiedy ludzie, którzy zgłaszają się do mnie, mówią mi, że ich czas jest cenny, aby „zmarnować” dokumentację, wymieniam ich tak szybko, jak to możliwe.

Wydaje się, że jeśli potencjalny pracownik uważa 48 praw władzy za etycznie lub moralnie akceptowalne, to lepiej byś je bez nich.

Jeśli NAPRAWDĘ chcesz być niezastąpiony (co możesz chcieć ponownie rozważyć po przeczytaniu wszystkich odpowiedzi ...) - po co przestać dokumentować kod?

Jest naprawdę genialny przewodnik na temat pisania nieusuwalnego kodu, który koniecznie powinieneś przeczytać: http://thc.org/root/phun/unmaintain.html

Cieszyć się! (Z pewnością tak ...)