Mój szef chce wyjaśnienia naszego kodu po angielsku, wiersz po wierszu

Zostałem specjalnie poproszony o udzielenie wyjaśnienia lub komentarza wiersz po wierszu (lub odpowiednio - na przykład obraz po obrazie itp.), Który mój szef chce móc przeczytać i śledzić.

Ponieważ nie jest programistą, nie może postępować zgodnie z kodem, dlatego chce, aby wszystko zostało przetłumaczone na angielski.

Czy ktoś wcześniej został o to poproszony?

Skomentowałem cały kod źródłowy i użyłem JSDoc do wygenerowania pełnej dokumentacji wszystkich funkcji, zmiennych itp. I zawierałem przykład implementacji oraz w pełni działające dema z komentarzami w całym tekście .

Czy jest coś jeszcze, co mogę zrobić, aby skomentować kod dla osób niebędących programistami?

To nie jest rozsądna prośba, prawda?

AKTUALIZACJA

W końcu udało mi się wyjaśnić, dlaczego nie warto było robić czasu, o co prosił. Jest rozsądnym facetem i po prostu nie rozumiał, na czym polega moja praca. Kiedy zobaczył ten post, myślę, że szybko zrozumiał, że nie była to normalna prośba.

Dostarczyłem dokumentację odpowiednią dla innego programisty (JSDoc i komentarze wbudowane - a także kilka dodatkowych uwag na temat problemów technicznych) oraz bardzo szeroki schemat blokowy głównej logiki programu, którą powinien podążać mój szef.

W końcu wszystkie strony były zadowolone i ruszyliśmy dalej.

Nie , to nie jest rozsądna prośba!

ROZMOWAJ GO Z NICH , lub niech ktoś inny go z tego wyciągnie. To irracjonalny pomysł, który, choć wykonalny, jest tak drogi, że tak naprawdę nigdy nie powinien zostać zrealizowany. Przegląd funkcji i podprogramów jest rozsądny, ale „wyjaśnienie” każdej linii kodu nie jest. Bardziej efektywne byłoby dla niego nauczenie się czytania języka, niż robienie tego.

Następną rzeczą, o którą poprosi, będzie tłumaczenie formuł matematycznych lub czegokolwiek innego na tekst angielski. Chociaż z pewnością jest to możliwe, wprowadza wiele miejsca na błędy i błędną interpretację i nigdy nie należy tego robić. Podobnie jak „tłumaczenie” kodu na angielski.

Czy masz dokumenty projektowe ? Są to angielskie wyjaśnienia tego, co robi kod. Menedżer niebędący programistą nie powinien potrzebować więcej.

Czy istnieje nagroda mikro-menedżera roku? Wygląda na to, że twój szef zasługuje na nominację. Ktoś, kto uważa, że ​​potrzebuje zrozumienia kodu wiersz po wierszu, ale nie chce nauczyć się go czytać bezpośrednio, jest tak doskonały jak mikro-manager, jak można sobie wyobrazić.

Jedną z zalet bycia programistą jest to, że trudność w zrozumieniu kodu uniemożliwia mikrozarządzanie w pewnym stopniu, przynajmniej na poziomie szczegółowego wdrożenia, przynajmniej przez zarządzanie nietechniczne, ponieważ nawet najbardziej wymagający mikromanager rozpoznaje, że są nad ich głową na tym poziomie. Ale geniusz twojego szefa może znaleźć sposób na zniszczenie silikonowej kurtyny.

I, jako bonus, marnuje ogromną ilość czasu programisty na tłumaczenie, nawet zanim użyje angielskiego tłumaczenia, aby zacząć sugerować różne ulepszenia (zakładam, że wie, jak kodować lepiej niż programiści, chociaż nie może przeczytaj kod i będzie mógł dzielić się swoją mądrością, gdy tylko ktoś ją przetłumaczy, w przeciwnym razie dlaczego miałby potrzebować tłumaczenia każdej linii?).

Więc nie, to nie jest rozsądna prośba i nigdy o niej nie słyszałem. I współczuję tobie. Myślę, że każdy może potrzebować zacząć po cichu szukać innej pracy, ponieważ kiedy zacznie używać tłumaczenia kodu jako narzędzia zarządzania, prawdopodobnie będzie to brutalne miejsce do pracy (er, bardziej brutalne miejsce do pracy).

Na plus, może uda ci się uzyskać nowy anty-wzór nazwany na cześć twojej sytuacji? Co powiesz na anty-wzór „Brudny węgierski rozmówki” po skeczu Monty Pythona, w którym sklep tytoniowy próbuje komunikować się z kimś, kto nie mówi po angielsku, używając węgierskiego rozmówki z komicznie fałszywymi tłumaczeniami?

Usiądź z nim i porozmawiaj z nim przez 10 wierszy kodu. Wyjaśnij każdy szczegół, dopóki oboje się nie zgodzicie, że rozumie go w takim zakresie, w jakim chciał.

Może to wszystko, czego szuka: wrażenie, jak wygląda twoja praca i jak wygląda oprogramowanie z twojego punktu widzenia. To dobrze w mojej książce.

Jeśli po tym nadal chce, abyś kontynuował, powiedz: zauważ, ile pytań musiałem zadać; wyobraź sobie, że musiałbym to wszystko wyjaśnić, nie mogąc zadawać pytań, skąd mógłbym wiedzieć, co uwzględnić, a co pominąć? Ile czasu zajmie, zanim wyniki będą dla Ciebie przydatne? Ile linii chcesz, abym zrobił w ten sposób?

Nie sądzę, żeby to była rozsądna prośba. KOD ŹRÓDŁOWY nie jest przeznaczony do czytania w języku angielskim (ani w żadnym innym języku).

Może boi się, że zmusisz swój kod do zrobienia czegoś, czego nie zaakceptuje lub o czym nie wie. W takim przypadku nie sądzę, że można coś z tym zrobić. Będziesz musiał napisać dokumentację lub przekonać go / ją do zatrudnienia kogoś do audytu twojego kodu.

To naprawdę jest bardzo proste:

• Zostałeś zatrudniony ze względu na swoje umiejętności programistyczne
• Twój menedżer nie ma tych umiejętności
• Ergo, twój menedżer nie powinien racjonalnie oczekiwać, że będzie w stanie w pełni zrozumieć, co robisz

Miałem podobne doświadczenie w poprzedniej pracy. Mój kierownik był księgowym (a więc zorientowanym na szczegóły na niskim poziomie) i nie rozumiał ani nie ufał programowaniu. Nie mogła pojąć, że jako osoba nietechniczna nie powinna oczekiwać, że będzie w stanie uchwycić najdrobniejsze szczegóły tego, co napisałem. Po wielu prośbach o nadmierną dokumentację i szkoleniach nietechnicznych użytkowników w zakresie zarządzania i modyfikacji kodu (tak, naprawdę), przestałem próbować ją wyrzucać i wprost odmówiłem. Analogia, którą wyjaśniłem, była prosta:

• Nie jestem księgową
• Nie powinienem oczekiwać, że zrozumiem każdą pojedynczą transakcję lub księgowanie na naszych kontach
• Nie oznacza to, że konta są błędne lub niewiarygodne, po prostu dlatego, że ich nie rozumiem
• Jest to możliwe dzięki zaufaniu osobie, która je skompilowała

Na koniec tak to dla mnie brzmi: kierownik, który ma trudności z zaufaniem swoim pracownikom; lub obawia się, że odejdą, i uważa, że ​​jest to skuteczny sposób na złagodzenie tego.

Jedynym rozwiązaniem tego jest usiąść i wyjaśnić, dlaczego nie ma to sensu. To twoja praca, aby zrozumieć kod i pozwalają na kogoś z podobnym zestawem umiejętności do Ciebie, aby je zrozumieć, a nie Twój menedżera. Pokazanie im tego wątku może być dobrym pomysłem (lub naprawdę, naprawdę okropnym, w zależności od ich osobowości).

Linia po linii jest absurdalna. To, co mogę zasugerować, to zaoferowanie generowania dokumentów z komentarzy i dawania mu tego. To wystarczyło w przypadku szeregu dotacji i audytów rządu kanadyjskiego, nad którymi pracowałem w przeszłości.

On nie dostanie linia po linii, ale dostanie metodę-by-metody, które powinny nadal być bardziej ziarnistość niż potrzebuje.

Niektóre istniejące rozwiązania, w zależności od platformy:

• C #: zamek z piasku
• Java: javadoc
• „C ++, C, Java, Objective-C, Python, IDL (smaki Corba i Microsoft), Fortran, VHDL, PHP, C # i do pewnego stopnia D.” : doksygen

Byłby o wiele szybszy, gdyby nauczył się czytać kod niż tłumaczyć cały kod dowolnej interesującej aplikacji na angielski. Poza tym próbowaliśmy tego z COBOL i to wcale nie pomogło. Jeśli nie chce się uczyć, ale chce sprawić, że jego ignorancja stanie się problemem kogoś innego, masz poważnie spiczastego szefa.

Wykorzystaj swoją wiedzę techniczną, aby prześladować swojego szefa.

1. Poinformuj go, że najpierw zajmie to tyle samo czasu, co w przypadku kodowania (możesz go przedłużyć).
2. Zapytaj go, jak aktualny powinien być ten dokument. Poinformuj go, że wszystkie zmiany kodowania potrwają teraz przynajmniej dwa razy dłużej.
3. Jeśli ty lub ktokolwiek znajdzie jakieś błędy, zapytaj go, czy powinieneś je teraz naprawić lub poczekać, aż skończysz kodowanie psuedo. Przypomnij mu o numerach 1 i 2.

Podobnie jak wszystkie sugestie złych rozwiązań, lepiej zidentyfikować problem. Może twój szef został dotknięty pytaniami technicznymi ze strony kierownictwa i czuje się zawstydzony, ponieważ nie jest w stanie odpowiedzieć. Może istnieć jedna szczególna sekcja kodu, która najbardziej go niepokoi, więc możesz ograniczyć to ogromne przedsięwzięcie tylko do tego obszaru.

Przesyłając próbkę, może dojść do wniosku, że jeśli nie rozumiesz, jak działa kodowanie (co to jest pętla i co robi z tymi wszystkimi elementami?), Nie ma znaczenia, w jakim języku jest. Jest lepszy zrozumienie aplikacji z perspektywy zaawansowanego użytkownika. Myślę, że to uczciwe, aby poinformować go, że wolisz pisać prawdziwy kod / wskazówkę - szukam innej pracy.

Dlaczego?

Komentarz linijka po linii nie jest rozsądny, ale o to zapytam: dlaczego tego chcesz?

Czy to dlatego, że ...

• chcesz w pełni zrozumieć, co robi oprogramowanie (niekoniecznie jak)?
• chcesz mieć pewność, że inny programista przejmie projekt, jeśli odejdę?
• chcesz zobaczyć, że wykonuję prawdziwą pracę?

Może być uzasadnione pragnienie i możesz uszczęśliwić swojego szefa, uzgadniając to z potrzebą.

Aktualizacja

Opierając się na Mikey'skomentarzach, być może powiedziałem to trochę zbyt otwarcie. Nie chodzi mi o to, że powinieneś dosłownie powiedzieć „dlaczego tego chcesz?”, Po prostu powinieneś to odkryć . Duże znaczenie ma brzmienie i ton głosu. W szczególności możesz powiedzieć coś takiego:

„Zastanawiałem się nad twoją prośbą o wyjaśnienie każdego wiersza kodu. Robienie tego w ten sposób jest trochę niezwykłe. Zastanawiałem się, czy może jest coś, czego nie komunikuję ci dobrze na temat mojej pracy. Co tak naprawdę chcesz zrozumieć na temat naszego kodu lub tego, co robię? Co tutaj próbujesz osiągnąć? ”

Oczywiście możliwe jest, że twój szef jest całkowicie nierozsądny. Ale bardziej prawdopodobne jest, że nie wie, jak dziwna jest ta prośba, i ma na myśli racjonalny cel.

Jeśli nie, zacznij polerować swoje CV. :)

Brzmi jak dobra okazja do wypróbowania programowania. Wygoogluj to. :)

Ale ... niekoniecznie jest to całkowicie nieuzasadniona prośba. Częścią twojego zadania (ważniejsza część, imo) jest przekazywanie algorytmu (algorytmów) innym programistom oraz, w razie potrzeby, osobom nietechnicznym. Wydaje mi się, że samotni genialni programiści, którzy nie potrafią się komunikować, są zawsze problematyczni.

W tym celu twój kod powinien być bardzo wyraźny (co oznacza: albo naprawdę samodokumentujący lub dobrze udokumentowany, a przez „samodokumentowanie” rozumiem, że zmienne i funkcje mają jedno znaczenie lub odpowiedzialność, a ich nazwy odzwierciedlają to wyraźnie). Twój szef może mieć dobre powody swojej prośby. Może (zgaduję tutaj) ty lub twój poprzednik macie reputację nieprzeniknionego, delikatnego kodu i to jest lekarstwo twojego szefa. Jest to trochę ekstremalne, ale może być dla ciebie pożytecznym ćwiczeniem. Zakładam, że wie, że pisanie lepszych dokumentów zajmuje dużo czasu (a jeśli tego nie zrobi, należy go uczyć - to tak jak pisanie pracy terminowej: pisanie zajmuje więcej czasu niż czytanie).

Nawet tłumaczenie wiersz po wierszu nie przekazuje skutecznie znaczenia każdego wiersza kodu. Programiści rozumiejący wiersz kodu zawsze znajdują się w kontekście wielu czynników. Wejdź w coś w rodzaju wielowątkowego kodu, a angielskie tłumaczenie nie będzie miało większego sensu niż surowy kod. Pomyśl o funkcjonalności rozłożonej na wiele funkcji / plików. Niektóre kody nie mają absolutnie żadnego sensu bez wyjaśnienia dużej ilości innego kodu. Spróbuj wyjaśnić różne części związane z wtryskiem zależności „linia po linii”, a zobaczysz, co mam na myśli. Prawie wszystko, co wykracza poza kod proceduralny funkcji Boga, będzie wymagało dużej wiedzy programistycznej, aby zrozumieć tłumaczenie na angielski. Spójrz także na coś tak prostego jak oświadczenie o decyzji if / else. Nie ma linii po linii, ponieważ następny wiersz zależy od danych w czasie wykonywania. Kolejna linia może być jedną z kilku możliwości.Zanim wyjaśnisz, czym zajmuje się twoja aplikacja, uczynisz z PM swojego programistę i oboje będziecie o 5 lat starsi.

Ponieważ uczyłem programowania, byłbym bardzo szczęśliwy, mogąc spróbować.

Szybko się dowie, że dostaje więcej, niż się spodziewał, co mnie zasmuci, bo lubię tłumaczyć :-)

Kiedy mówisz o swoim „szefie”, czy jest to „menedżer średniego szczebla odpowiedzialny za ciebie / twój zespół”? lub właściciela Twojej firmy? Czy otrzymujesz wynagrodzenie „za godzinę”, czy „z pensji”?

JEŻELI twój szef jest menedżerem średniego szczebla, który jest odpowiedzialny, ROZMÓW DO SWOJEGO BOSS, zwróć uwagę, że aby spełnić wymagania szefa, Twoja produktywność w firmie spadnie do 1/3 tego, co mogłoby być.

JEŻELI twój szef jest „facetem, który podpisuje czeki”, wyjaśnij mu to samo, tylko bardziej dyplomatycznie. Twoje zadanie zmieniło się z „Napisz kod” na „Napisz kod, napisz wyjaśnienie kodu, wyjaśnij wyjaśnienie”.

Schemat blokowy przyniesie mu prawdopodobnie więcej korzyści. Jest to z pewnością niezwykła prośba i niewiele mówi o nim jako menadżerze.

Fakt, że twój szef jest gotowy poświęcić trochę czasu na zrozumienie napisanego przez ciebie kodu, możesz wykorzystać dla swojej korzyści. Spróbuj przedstawić go Ogórkowi: http://cukes.info/

i spraw, aby Twój szef napisał dla ciebie test BDD w przyszłości.

Nie powinien zadawać sobie trudu, aby o tym wiedzieć. Powiedz mu, że wdrażanie oprogramowania może ulec zmianie. Projekt wydarzenia może ulec zmianie. Powiedz mu o ukrywaniu informacji, enkapsulacji i abstrakcji.
On, jako część twojego zespołu, jako klient twojego kodu, w szerszym znaczeniu, powinien pracować tylko z wyraźną, wysokopoziomową abstrakcją tego, co robi twój kod. W ten sam sposób każda warstwa kodu działa z inną warstwą kodu innej osoby. Wiedząc o tym więcej, spowolni go i ryzykuje, że będzie przyjmował założenia w oparciu o wewnętrzne działanie twojego kodu. Te założenia przestaną obowiązywać, gdy będziesz musiał zmienić kod, co staje się problemem, jeśli zbuduje on jakikolwiek system lub proces na ich podstawie.
A także konieczność wykonywania tego rodzaju pracy zmniejszy Twoją wydajność. Będziesz musiał nie tylko wprowadzać kolejne zmiany w dwóch różnych miejscach, ale także negatywnie wpływać na morale pracy, co jeszcze bardziej obniży wydajność.

Piękno języka angielskiego polega na tym, że pięknie się zaciemnia. Jeśli wykorzystasz to na swoją korzyść, możesz nigdy nie mieć odwagi poradzić sobie z tego rodzaju prośbą ponownie. Wziąłbym mały fragment kodu jako próbkę, ale taki, który jest bardzo abstrakcyjny i wcale nie jest łatwy do zrozumienia. Następnie napisałbym komentarze w angielskim języku technicznym, tak jakbyś pisał je w rozdziale książki programistycznej. Im dłużej i bardziej skomplikowane, tym lepiej. Powiedz mu, ile godzin zajęło Ci udokumentowanie tej jednej funkcji. Następnie wyjaśnij, że jest to tylko 1/10 z 1% (użyj rzeczywistych liczb opartych na wierszach kodu, jeśli możesz, są one prawdopodobnie gorsze od tego) rzeczywistej podstawy kodu. Kiedy zda sobie sprawę, że nie ma pojęcia, co mówi angielskie tłumaczenie i że zrobienie tego poziomu dokumentacji zajmie 20 000 roboczogodzin, wycofuje się dość szybko. Ale bardzo szczerze staraj się wypełnić swoje zadanie. Don; t spróbuj tego, jeśli nie możesz tego zrobić, a on podejrzewa, że ​​go grasz.

To wygląda na kandydata do specjalnego świątecznego paska szefa Dilberta ze spiczastymi włosami ! Jego prośba z pewnością nie brzmi rozsądnie na pierwszy rzut oka.

Pomijając humor, spróbuj dowiedzieć się, czego naprawdę potrzebuje i dlaczego, a następnie poinformuj go, ile będzie to kosztować w dolarach lub godzinach, i pozwól mu zdecydować, czy chce wydać na to tyle pieniędzy.

Jeśli chodzi o ciebie, policz godziny, jakie zajmie ci spełnienie jego pozornie dziwnej prośby, a następnie ustal, czy nie lepiej byłoby zainwestować ułamek tej ilości czasu w znalezienie nowej pracy dla pracodawcy gotowego cię leczyć jako profesjonalista!

Zabierz go do swojego biura i opowiedz mu o swoim kodzie.

W pewnym momencie uświadomi sobie, że wysunął absurdalne żądanie, i odejdzie i nigdy więcej nie będzie ci przeszkadzać.

Jeśli nie poddasz się jego żądaniom, aby pomóc mu w zrozumieniu twojego kodu, znajdzie inne, ale równie absurdalne sposoby, aby cię wkurzyć.

Jest to przypadek, w którym uspokajanie działa lepiej niż ścieranie.

Byłoby bardzo miło, gdybyśmy mieli do tego tłumacza „Język X na angielski”. Wtedy można się uśmiechnąć i powiedzieć: nie ma problemu, szefie, będziesz miał to za minutę. A potem przychodzi wiadomość z kilkoma megabajtami tekstu o treści:

• Niech będzie nową tablicą liczb całkowitych z 20 elementami.
• Niech x będzie zmienną do przechowywania liczb całkowitych.
• Ustaw x na 0
• Podczas gdy x jest mniejszy niż 20, rób to, co jest zalecane w następnych 2 wierszach
• ustaw element tablicy z indeksem x na wynik wywołania nThPrime z argumentem x + 1
• zwiększyć x o 1
• ....

Inną opcją byłoby odtąd sugerowanie programowania w Szekspir .

Mój szef chce wyjaśnienia naszego kodu po angielsku, wiersz po wierszu

Twardy.

Ponieważ nie jest programistą, nie może postępować zgodnie z kodem, dlatego chce, aby wszystko zostało przetłumaczone na angielski.

Jeśli nie jest programistą, nie powinien czytać kodu. W ogóle.

Zamiast tego zapewnij dokumentację wysokiego poziomu.

To nie jest rozsądna prośba, prawda?

Nie.

Jako programista naprawdę masz „dwa” zadania.

Pierwszym z nich jest tworzenie dobrych programów. Drugim jest „sprzedaż” ich klientom wewnątrz i na zewnątrz firmy.

Prośba szefa „boli” twoją pierwszą pracę. Dokumentowanie programów zajmuje więcej czasu. Z drugiej strony sprawia, że ​​ciężko pracujesz nad swoją „drugą” pracą.

Twój szef prosi cię o udokumentowanie programu w języku angielskim dla JEGO korzyści, i prawdopodobnie dla korzyści osób, z którymi ma do czynienia, w firmie i poza nią. Jeśli pomożesz mu wykonywać swoją pracę, powinno to działać na twoją korzyść na dłuższą metę, kiedy poprosisz go o więcej sprzętu, personelu lub pieniędzy na podwyżki. W końcu poprosił cię o więcej pracy.

Myślę, że BDD będzie dobrze pasować do tego problemu, chociaż wydaje się, że twój projekt jest już prawie ukończony, więc trochę trudno go teraz wdrożyć, więc bardziej przypomina to na przyszłość.

W przypadku BDD przypadki użycia są opisywane jako czytelne dla ludzi dokumenty, które są następnie tłumaczone na zautomatyzowane testy funkcjonalne.

Prawdopodobnie jest to dobry moment, aby dowiedzieć się czegoś takiego jak ANTLR . Weź ANTLR, weź gramatykę swojego języka, parsuj cały posiadany kod, przeglądaj AST generując opisy oparte na szablonie dla każdego węzła, więc i++jest to opisane jako increase i by 1 using postfix increment operator. To powinno być naprawdę zabawne. Twój szef może również chcieć włączyć to narzędzie do skryptu kompilacji, więc za każdym razem, gdy wprowadzisz jakieś zmiany, otrzyma około 20 MB wiadomości e-mail z opisem działania nowej wersji.

PS Żartowałem, to idiota.

Chociaż zgadzam się, że jest to nieuzasadnione żądanie, twój szef może docenić coś takiego jak dane wyjściowe Docco , które dzielą twój kod i komentarze wiersz po wierszu lub klauzula po klauzuli na dwukolumnowe wyjście HTML, z kodem na jednym po drugiej stronie i proza. Oczywiście musisz sam wpisać komentarze, ale prezentacja jest raczej ładna IMHO, nawet dla nietechnicznych czytelników. Zobacz na przykład sekcję z komentarzem wiersz po wierszu kodu z komentarzem dla Underscore.js . Istnieją również wersje skryptów Python i powłoki.

Możliwe, że twój szef jest po prostu niedoinformowany i zastraszony, ale w rzeczywistości jest rozsądną osobą. Jeśli tak, rozumowanie z nim może zadziałać - swobodna rozmowa, w której obiecujesz dostarczyć „to, czego naprawdę chce”, tj. przewodnik po prozie na temat tego, co robi program.

Jeśli chodzi o „moją drogę lub autostradę”, lepiej sprawdź teraz swój gaz.

Mógłbyś napisać kilka testów akceptacyjnych przy użyciu frameworku opartego na zachowaniu, takiego jak ogórek ? To nie wyjaśni kodu; wyjaśni, co robi, w języku naturalnym. Ma również tę zaletę, że jest wykonywalny, więc zawsze możesz mieć pewność, że dokumentacja jest aktualna, ponieważ jeśli nie, tester będzie czerwony.

Sprawdź wideo wprowadzające. Być może jest to dobra okazja do znalezienia nowego szefa ... ;-)

Twój menedżer prawie na pewno jest zakłopotany faktem, że nie rozumie, co ludzie robią, którymi zarządza, i nie ma wystarczającego zaplecza, aby zrozumieć wyniki, które produkują.

Wątpię, żeby dokładnie przemyślał to rozwiązanie i na pierwszy rzut oka wydawało mu się to rozsądne. Ale głównie dlatego, że nie rozumie, czym właściwie jest kod programowania.

Każdy programista rozumie absurdalność tej prośby, ale robimy to, ponieważ intuicyjnie wiemy, że kiedy przejdziesz przez język, wszystko, co zostanie ujawnione, to algorytm, który jest równie tajemniczy.

// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
    // call the server's init function passing our current ID and address
    s->init(proc->id,*addr);
    // call log::info with our custom message
    log::info("Starting server %s",s->name);
    // Set s to the value returned by the server's next() function
    s=s->next();
} // end of loop

Problem polega na tym, że podczas gdy komentarze wyjaśniają, co robi każda linia, nadal nie masz pojęcia, co naprawdę robi kod, chyba że zrozumiesz, jakie są wszystkie konsekwencje. To oczywiste, że jesteś programistą i widziałeś już ten wzór; ale pokaż to komuś, kto rozumie tylko sprzedaż, a po przeczytaniu komentarzy będzie tak samo zdezorientowany jak wcześniej.

Możesz zaoszczędzić czas , ucząc swojego szefa podstawowego programowania. Jeśli chce przeczytać Twój kod, daj mu narzędzia, aby to zrobić. Większość języków jest dość zwarta pod względem składni, a nauka struktury zajmuje tylko godzinę lub dwie. Prawie na pewno zrezygnuje po kilku dniach, ale przynajmniej będzie wiedział, co przekazuje, a co ważniejsze, dlaczego nie chce czytać twojego kodu.

IMHO ... jeśli jest odpowiedzialny za wykonanie zadania, powinien wiedzieć, jak to działa ... :)