Mój klient chce 25% komentarzy w moim obecnym projekcie, jak zareagować? [Zamknięte]

96

młodszy programista tutaj.

Obecnie pracuję sam nad aplikacją internetową dla dużego klienta mojej firmy. Zacząłem w zeszłym miesiącu. Klient chce co najmniej 25% komentarzy w każdym swoim projekcie oprogramowania.

Sprawdziłem kod poprzednich aplikacji i oto moje spostrzeżenia:

  • każdy plik zaczyna się od bloku komentarza (pakiet, data ostatniej aktualizacji, nazwa mojej firmy i prawa autorskie)
  • wszystkie zmienne są komentowane ich nazwami // nameOfCustomer public String nameOfCustomer

  • wszyscy pobierający i ustawiający są komentowani

  • bardzo mało przydatnych komentarzy

Wygląda na to, że programiści umieszczają tyle komentarzy, ile mogą, aby osiągnąć ten próg 25%, niezależnie od jakości i użyteczności. Moja firma mówi mi, że „robimy to tak, jak chce tego klient”.

Nie rozmawiałem o tym bezpośrednio z klientem. Oto moje dotychczasowe argumenty:

  • bezużyteczne linie do czytania i pisania (strata czasu)
  • komentarze czasami nie są aktualizowane (źródło nieporozumień)
  • programiści rzadziej używają lub ufają prawdziwym przydatnym komentarzom

Jaka jest twoja rada na ten temat? Jak mam poradzić sobie z sytuacją?

Rudzik_
źródło
162
To niedorzeczne. Jeśli jednak tego właśnie chce klient, a klient płaci ci dobre pieniądze, aby je zdobyć, to mu to dajesz.
Robert Harvey
20
25% linii (co oznacza, że ​​nigdy nie umieszczasz komentarza w tym samym wierszu co kod) lub 25% bajtów ?
RonJohn,
10
Lepiej uważaj tutaj. Zwykle jest taki powód oczekiwań ... Jeśli powiesz swojemu klientowi, że te komentarze są bezużyteczne, on / ona może nadal chcieć 25% komentarzy (bez względu na powód), ale teraz BEZ tych, które określasz jako bezużyteczne. , możesz mieć więcej kłopotów ... Czasami argumenty klientów są tak daleko idące, że cię to
zdziwi
19
Jest to lekcja przedmiotowa reguły, którą będziesz miał okazję zaobserwować w swojej karierze: rzecz, którą mierzysz, to rzecz, którą dostajesz . Otrzymałeś metrykę dla komentarzy, dlatego komentarze są tym, co dostaniesz. Bardziej rozsądny klient dostarczy Ci dane dotyczące wydajności, poprawności, niezawodności i kosztów, a następnie dostaniesz te rzeczy. Ale nie masz rozsądnego klienta.
Eric Lippert,

Odpowiedzi:

115

Wszystkie pozostałe odpowiedzi i komentarze naprawdę rzuciły mnie na pętlę, ponieważ są one tak sprzeczne z moją pierwszą reakcją i tak sprzeczne z postawą, której byłem świadkiem u moich współpracowników. Chciałbym więc opisać alternatywne podejście, choćby ze względu na to, że jest głosem odrębnym .

Główną zasadą tej odpowiedzi jest „Zachwycaj klienta”. Zadowolenie klienta oznacza nie tylko spełnienie jego oczekiwań; oznacza to dogłębne zrozumienie ich próśb, dzięki czemu można zinterpretować to, co mówią, w sposób, w jaki mają na myśli, i wykraczać poza to, o co proszą. Wydaje się, że inne odpowiedzi kierują się zasadą złośliwego przestrzegania zasad, co jest dla mnie obrzydliwe; a poza tym jest wątpliwa praktyka biznesowa, ponieważ jest to zły sposób na zdobycie stałych klientów.

Dla mnie, kiedy słyszę, jak klient mówi „Chcę 25% komentarzy”, jest to początek okna dialogowego. Dla mnie jasne jest, że implikacja tutaj brzmi: „Chcę dużo tekstu opisowego, aby nowi użytkownicy w tej bazie kodu mogli szybko zacząć działać”, a nie „Chcę, abyś dodał losowość w określonej kategorii składniowej”, tak jak inne odpowiedzi wydaje się, że bierze. I potraktowałbym to żądanie poważnie i zamierzam napisać wiele opisowych, pomocnych komentarzy, kierując nowicjusza do struktury kodu, wskazując zaskakujące decyzje inżynierskie i nakreślając uzasadnienie, które się do nich przydało, i podając angielski na wysokim poziomie opisy skomplikowanych sekcji kodu (nawet jeśli nie mają żadnych niespodzianek). Ta intencja i zrozumienie jest punktem wyjściadyskusji - zanim jeszcze zaczniemy rozmawiać. Dla mnie implikacja wniosku jest tak jasna, że ​​nawet nie potrzebuje tego wyjaśnienia; ale jeśli dla ciebie nie jest jasne, powinieneś oczywiście się z nimi sprawdzić!

Okej, więc gdzie idzie okno dialogowe, jeśli to jest punkt początkowy? Następna część okna dialogowego wygląda następująco:

  1. Spodziewałbym się, że będzie to poważny dodatkowy wysiłek, być może w drugiej fazie projektu, która wykracza poza produkcję narzędzia, na którym zależy im praca. Dyskusja na temat tego procesu i dlaczego jest to dodatkowa praca, może potrwać kilka minut, ale pominę go tutaj, ponieważ jako profesjonalny programista oczekuję, że wiesz, jak ciężko jest robić dobre komentarze.
  2. „Poważny dodatkowy wysiłek” oznacza, że ​​możemy potrzebować dłuższego budżetu i większego budżetu pieniężnego; lub może być konieczne zmniejszenie budżetu funkcji; lubmożemy potrzebować kompromisu co do jakości i ilości komentarzy. Ta część będzie trochę do negocjacji. Ale moim zdaniem powinieneś być bardzo ostrożny w kwestii kosztów wykonania tej dodatkowej pracy i upewnij się, że jest to tak ważna cecha dla klienta, że ​​jest on skłonny ponieść te koszty. A jeśli są - świetnie! Dostajesz dodatkowy czas i pieniądze, a oni otrzymują komentarze wysokiej jakości. Wszyscy wygrywają. A jeśli okaże się, że funkcja komentowania nie jest dla nich tak ważna, że ​​są gotowi stracić możliwość wymazywania widżetów lub pozwolić, aby termin przeszedł do późnego Granuarium, 20 x 6, wtedy wszyscy wygrywają ponownie: otrzymują produkt, który chcesz i nie musisz poświęcać dodatkowego wysiłku, aby tworzyć wysokiej jakości komentarze.

Tutaj myślę, że okno dialogowe nie powinno iść:

  1. Nie groż klientowi komentarzami niskiej jakości. Pozwól im pomóc wybrać poziom wysiłku, jaki chcą wydać i za który są gotowi zapłacić. Nie obiecuj im 25% komentarzy, a następnie poinformuj ich, że zamierzasz dotrzymać tej obietnicy, automatycznie generując losowość po zbudowaniu projektu.
  2. Nie ukrywaj swoich planów. Nie obiecuj im 25% komentarzy, a następnie automatycznie generuj losowość bez informowania ich, że to właśnie zrobisz. Kiedy zauważą (a nie jeśli), oboje tracicie duże znaczenie: są niezadowoleni z produktu, który dostali, i dostajecie negatywne słowa ustne.
  3. Nie próbuj ich przekonywać, że nie chcą komentarzy. Wyraźnie chcą komentarzy. Omów kompromisy różnych podejść: tak! Omów alternatywne sposoby uczynienia bazy kodu nową przyjazną: tak! Powiedz im, że nie wiedzą, czego chcą: eh, nie. Chcesz z nimi współpracować, aby uzyskać to, czego chcą; więc zrozum, co to jest i wymyśl, jak najlepiej dostarczyć im to w zatwierdzonym budżecie, nadając priorytet funkcjom, na których im najbardziej zależy, jeśli zasoby, które mają, są niewystarczające.
  4. Nie usprawiedliwiaj się, jak trudne są komentarze. Pisanie kodu jest trudne; debugowanie kodu jest trudne; pisanie komentarzy jest trudne. Gdyby to było łatwe, nie zatrudnialiby cię. Po prostu pomiń skargi i przejdź od razu do punktu, na którym im zależy, a mianowicie, jak wpływa na nich dodatkowy wysiłek.
Daniel Wagner
źródło
3
Mile
widziane
9
@ThorstenS. Firma, w której pracuję, wykonuje przeważającą część swojej pracy dla przemysłu obronnego. Może chcesz sprawdzić swoje moce psychiczne. Nigdy też nie powiedziałem „nie interpretuj ich życzeń, jak je napisali”: traktowałbym „25% komentarzy” jako poważną, ale przypadkową prośbę - prawdziwa prośba to „duża część pisma technicznego”, a 25% to tylko wskazówka na temat poziomu wysiłku, jaki spodziewają się wejść w to ciało, prawdopodobnie wybrana zasadniczo arbitralnie, ale mimo to cel, którego nie można przegapić.
Daniel Wagner,
12
Gdybym zatrudniał programistę, pan Daniel Wagner jest facetem, którego chciałbym zatrudnić.
Joe Gayetty
5
To świetna odpowiedź, ponieważ stara się zidentyfikować i odpowiedzieć na cel wniosku, a nie na jego literę. IMO Jest to różnica między deweloperem a kimś, kto pisze kod.
Justin Ohms
6
Dobrze byłoby również wyraźnie zaznaczyć, że komentarze te zwiększą koszty utrzymania . Raz utworzone muszą być stale aktualizowane , w przeciwnym razie są stratą czasu i pieniędzy. (Czekam do jutra na +1, więc faktycznie dostaniesz przedstawiciela;) Zasługujesz na to.)
jpmc26
83

Klient jest królem. Jako wykonawca spełnisz wszystko, co klient zdefiniował jako standard jakości. Lub ryzykujesz, że będziesz na zewnątrz.

To powiedziawszy, bardzo ważne jest, jak zdefiniowane są (tutaj słabe) standardy jakości:

  • Umowne standardy jakości: dostarczony kod musi być zgodny, w przeciwnym razie stanowi naruszenie umowy. Bez wyboru.

  • Formalne korporacyjne standardy jakości: nawet jeśli działa idealnie, kod, który nie jest zgodny, będzie uważany przez tak wiele osób za złą jakość, że będziesz stary, zanim przekształcisz je wszystkie w lepszą praktykę. Gorzej: do automatyzacji i legalizacji takich wskaźników jakości (np. Kostki sonaru ) można użyć dobrze znanych narzędzi . Prawie nie ma wyboru.

  • Kryteria ad-hoc określone przez kilka osób u klienta. Tutaj możesz zaangażować się w dyskusję. Jest nadzieja :-)

W tym ostatnim przypadku może istnieć pewna elastyczność i możesz spróbować dyplomatycznie przedstawić argument. Oto kilka argumentów przemawiających przeciwko kryteriom klienta:

  • Problem z wydajnością: kodowanie odbywa się dwukrotnie (raz w języku angielskim i raz w kodzie).
  • Problem z dokładnością: jeśli zmiany są wprowadzane w kodzie, należy je wprowadzić w komentarzach, w przeciwnym razie komentarze mogą stać się bezużyteczne.
  • Problem z refaktoryzacją: narzędzie do refaktoryzacji nie przetwarza nazw zmiennych w komentarzach.
  • Kwestia ryzyka: niejednoznaczność (lub starzenie się) komentarzy może powodować zamieszanie i ryzyko zwiększenia liczby błędów.
  • Ilość to nie jakość
  • Ta zabawna kolekcja bezużytecznych komentarzy na StackOverflow .
  • Ten artykuł dowodzi, że wysoki współczynnik komentarzy może być nawet oznaką zapachu kodu.

Ale zamiast mówić przeciwko złemu i konfrontować klienta, możesz po prostu promować lepsze podejścia:

  • Czysty kod (zasugeruj książkę swojemu klientowi: jest przekonująca sekcja poświęcona komentarzom i kodowi samo-dokumentującemu).
  • Praktyka dokumentacyjna: najtrudniejsze do uchwycenia rzeczy, a zatem najcenniejsze informacje, takie jak na przykład relacje i interakcje między klasami, lepiej udokumentować w osobnym dokumencie (na przykład w obrazie UML zamiast 1000 słów komentarza?)

Jeśli klient nadal nie jest przekonany, możesz zaproponować eksperymentalną alternatywę, korzystając z narzędzi generujących automatycznie dokumentację z komentarzami, takimi jak javadoclub doxygen. Zaproponuj, aby przenieść fokus z ilości (25% kodu) na jakość (wygenerować zrozumiały javadoc).

Christophe
źródło
7
Jeśli klient jest królem, to po prostu pokazuje, jak nieefektywne są takie królestwa klientów!
Steve
82
Klient jest królem. Więc jako kontrahent spełnisz wszystko, co klient określił jako standard jakości. Albo ryzykujesz, że nie będzie cię. Moje doświadczenie było odwrotne. Ci, którzy dają swoim klientom to, co myślą, a czego nie potrzebują, nie przetrwają bardzo długo. W rzeczywistości rezerwuję tę formę nadużyć tylko dla prawdziwych klientów będących problemami - a druga dawka nigdy nie była potrzebna.
David Schwartz,
6
@DavidSchwartz tak, z pewnością. Czasami klienci myślą, że czegoś potrzebują, ale naprawdę potrzebują innego. Przekonaj się do konsultanta lub programisty, a 2/3 mojej odpowiedzi dotyczy właśnie tego. Wszystko zależy jednak od kontekstu umownego i poziomu zaufania między dostawcą a klientem. Należy więc przypomnieć, że zasada klienta jest królem (w rzeczywistości kilkakrotnie doświadczyłem z klientami, że po długiej debacie na temat optymalnego rozwiązania podniosłem to zdanie, co spowodowało nagłą zmianę nastawienia i staranne przemyślenie argumentów ;-) ).
Christophe
7
„Problem z dokładnością: jeśli zmiany są wprowadzane w kodzie, należy to zrobić w komentarzach, w przeciwnym razie komentarze mogą stać się bezużyteczne”. Powiedziałbym, że to nawet gorsze niż po prostu bezużyteczne . Komentarz, który jest nieaktualny, może bardzo szybko zmienić się w błąd (lub kogoś, kto go odwróci, ponieważ uważa, że ​​to błąd), gdy spodziewasz się, że jest to źródło prawdy i zaufaj mu.
Hamatti
11
@Hamatti Rzeczywiście. Kiedyś spędziłem sporo czasu odszyfrowując pierwotne zamiary za wierszem, który brzmiał:i++; // count down
TKK
18

Klient chce co najmniej 25% komentarzy w każdym swoim projekcie oprogramowania.

Czy klient naprawdę chce 25% komentarzy, czy też chce, aby Twój kod był jak najbardziej opisowy?

IMHO, klient wie, czego chce, ale nie tego, czego potrzebuje. Ponieważ klient nie jest samym programistą i otrzymuje opinie od swoich pracowników / klientów, Twój klient widzi tylko górną część góry lodowej.

Myślę, że twój klient ma pewną pseudo-wiedzę i chce, aby kod był dobrze udokumentowany oraz łatwy i tani w utrzymaniu, a narzędziem do tego są komentarze (w jego umyśle).

Spróbuj z nim porozmawiać i przygotuj kilka fragmentów kodu z dobrze napisanym kodem, który tłumaczy się sam, a jeszcze innym źle napisanym z komentarzami. Tylko kilka linii. Pokaż to w razie potrzeby i użyj go jako obraz do swoich słów.

Porozmawiaj ze swoim klientem / przełożonym / kimkolwiek i postaraj się powiedzieć im o nowoczesnych zasadach kontroli wersji (nie ma potrzeby komentowania na początku pliku) i wyczyść kod (również polecam książkę ), a tym samym wynikowy kod wyjaśniający.

Być może, jeśli potrafisz pokazać go wystarczająco dobrze i sprawić, że klient zrozumie, że chce czystego kodu, a nie tylko komentarzy, ty i twój zespół możecie napisać lepszy kod (z dużo mniej komentarzy) i natychmiast pokazać, że jesteś dobrym programistą wartym zachowania .

Chrᴉz
źródło
13
Kod wyjaśniający to piękna zasada. Niestety w prawdziwym świecie nie działa to tak dobrze. Interfejsy i złożone procesy wewnętrzne wymagają udokumentowania, a samo wybranie ładnych nazw nie wystarczy. Jakie jednostki to te wartości? Czynniki skalujące? Przykładowe stawki? Kiedy można bezpiecznie wywoływać tę metodę, a kiedy nie? Jakie wyjątki zostaną zgłoszone dla jakich warunków? I tak dalej, i tak dalej. To sprawia, że ​​twój kod jest łatwy do utrzymania. Rzeczywisty świat ma złożoność, której fragment kodu nigdy nie będzie reprezentował, i dlatego potrzebujesz go odpowiednio udokumentować.
Graham,
2
@Graham Tak, komentarze nie są całkowicie nieuniknione. Ale komentarze są jak kod: im więcej robisz, tym więcej trzeba zachować. Zachowanie zwięzłości pomaga wierzyć.
Robert Dundon
Nie chcę powiedzieć, że momenty są całkowicie bezużyteczne, ale komentarze dokładnie takie jak nazwa funkcji lub zmiennej nie są przydatne. Krótki fragment kodu powinien pokazywać, że jest to możliwe bez komentarzy i nie powinien wymuszać środowiska bez komentarzy. Jeśli chcesz pokazać, jakie wyjątki zostaną zgłoszone lub dalej opisać funkcjonalność, możesz użyć znacznika podsumowania dla funkcji. Jeśli chcesz zasygnalizować zależności,
zamodeluj
@Chriz Oczywiście, zgadzam się. Jeśli komentarze nie dodają informacji, pomiń je. Ale, jak powiedziałem w innej odpowiedzi, procent to tak naprawdę test zapachu kodu. Uzasadniasz to, audytor to sprawdza, wszyscy idą dalej. Problemem jest ktoś, kto uważa, że ​​ich kod naprawdę wyjaśnia, i nie myślał o tych wszystkich sprawach.
Graham,
12

To przypomina mi te głupie odpowiedzi Przepełnienie stosu, które widzisz, które składają się z jednego wiersza, po którym dosłownie: „trochę tekstu tutaj, aby uzyskać minimalny limit znaków”.

Kiedy tak się dzieje, można wysunąć argument, że winne są dwie grupy ludzi:

  1. Ludzie, którzy ustalili limit - wyraźnie jest on nadmierny i uniemożliwia przesyłanie poprawnie sformułowanych informacji bez powodowania sztucznego hałasu

  2. Ludzie, którzy przesłali informacje, które nie zostały poprawnie sformułowane, dodali sztuczny hałas, gdy system poprosił ich o dodanie bardziej rzeczywistej substancji

Czasami pytanie będzie zarówno proste, jak i tematyczne, i nie ma nic więcej do powiedzenia niż kilka słów. Jest to jednak niezwykle rzadkie. W prawie wszystkich przypadkach można powiedzieć o wiele więcej treści. Jeśli nic więcej, powinno być oślepiająco oczywiste, że sposobem na ominięcie ograniczenia postaci nie jest po prostu zrzucenie losowego hałasu na swój post.

Ta sytuacja związana z komentowaniem jest prawie taka sama. Twoi programiści przyjęli prośbę o komentarze i wdrożyli ją, zrzucając losowy szum do swojego kodu. Dokumentowanie nazw zmiennych tuż obok deklaracji zmiennych to wandalizm . To nigdy nie powinno się zdarzyć.

„Ale jak inaczej możemy uzyskać 25%?” Pisząc aktualne komentarze merytoryczne. Użyj więcej słów, lepsze słowa, najlepsze słowa, aby udokumentować efekt działania. Rozwiń swoje wyjaśnienia. Opisz bardziej szczegółowo przypadki krawędzi.

Jednak wracając do pierwotnego punktu, klient jest tu częściowo winny, ponieważ „25% kodu źródłowego” jest wyjątkowo arbitralne. Ostatecznie jednak są klientami, więc wykorzystaj to, co najlepsze. Ale mam na myśli „najlepszy”. Nie „najgorsze”, jak to się dzieje do tej pory.

Lekkość Wyścigi na orbicie
źródło
5

Nie wiem, o co tyle zamieszania w związku z tym wymogiem.

Po prostu doxygenacji twojego kodu prawdopodobnie masz już około 10%. Weźmy jeszcze 5% komentarzy, które sam dla siebie napisałeś (niektórzy piszą więcej, ale 5% wydaje się być ostrożnym szacunkiem, jeśli nie złożyłeś przysięgi milczenia). W tym momencie jest to około 15% (tak tak, wiem, 5% z 90% to mniej niż 5%, nie dziób). Jeśli twój doksygen jest mniejszy niż 10%, być może twoje metody są bardzo długie; zwykle dobrze jest podzielić je na mniejsze (głównie prywatne / chronione) lub użyć bardziej ogólnych klas pomocników itp.

Teraz, w pozostałej części tekstu komentarza - umieść uwagi projektowe i scenariusze użycia w komentarzach na poziomie klasy / pliku. Masz tabele lub ASCII-art (lub kod doxygen, który generuje ładniejsze rzeczy podczas renderowania). Nie wiem oczywiście, o co chodzi w twoim projekcie, ale wierzę, że możesz to zrobić bez żadnych fałszywych komentarzy (innych niż płyta kotłowa doxygenacja) i uzyskać coś zbliżonego do 25%.

Jeśli tylko, powiedzmy, 20%, a nie 25% - jestem pewien, że klient podał tę liczbę jako coś arbitralnego i będzie z tym dobrze. W każdym razie porozmawiaj z nimi, aby omówić, co powinny obejmować komentarze; i pokaż im przykładowy plik z komentarzem, aby zobaczyć, czy są zadowoleni. Jeśli tak, to tyle, jeśli myślą, że czegoś brakuje, powie ci, czego brakuje. Nie powiedzą ci: „Nie możemy zaproponować żadnego dodatkowego komentarza, ale nadal chcemy, abyś go dodał”.

PS - spójrz na standardowy kod kontenerów Java, aby zobaczyć, jak możesz osiągnąć 70% lub mniej więcej ...

einpoklum
źródło
5

Posiadanie 25% komentarzy w kodzie jest doskonałym celem i sprawia, że ​​klient jest szczęśliwy. Teraz pisanie 25% gównianych komentarzy wypełniających, takich jak „i + = 1; // wzrost i o 1”, powinno znajdować się pod tobą, więc nie spiesz się, pisz przydatne komentarze i ciesz się poczuciem, że faktycznie zarabia się, że należy zrobić coś, co powinieneś zrobić tak czy siak.

gnasher729
źródło
To też fajne +1. Nie wiem, czy może istnieć dobry cel wyrażony liczbą komentarzy, ale może wielu z nas osiąga ten „cel” w przydatny sposób, nie wiedząc… Niedawno znalazłem stary kawałek kodu który napisałem w latach 80. na początku mojej kariery, z innowacyjnym algorytmem o wysokiej wydajności: ma tylko 10% komentarzy, ale z mocą wsteczną chciałbym dodać więcej ;-)
Christophe
4

Wszyscy wiemy, że jest to bzdura. Ciekawe pytanie tutaj

jak zareagować

Wierzę w to, aby problemy były widoczne. Chciałbym wykorzystać fakt, że pieniądze mówią.

Poproś mnie o zrobienie tego, a powiem na pewno, że doda 1% do mojej oferty. Och, ale doda 20% do przyszłych ofert konserwacji.

Tylko raz pytają, dlaczego nauczę ich, że dobre imię to unikanie potrzeby komentowania.

Jako alternatywę zaproponuję stworzenie dokumentacji mającej na celu uzyskanie przez programistę utrzymania ruchu określonego zestawu założonych kwalifikacji, aby przyspieszyć pomysły związane z projektem. Albo oczywiście, mogę dać ci 25% komentarzy. Zależy od Ciebie.

candied_orange
źródło
3

Tak, rozumiem twoją frustrację głupią zasadą. Czytałem wiele programów z bezużytecznymi komentarzami, takimi jak

x = x + 1; // add 1 to x

I mówię do siebie: TO TO oznacza znak plus !! Wow, dzięki, że mi powiedziałeś, że tego nie wiedziałem.

Ale powiedziawszy, klient płaci rachunek. Dlatego dajesz im to, czego chcą. Gdybym pracował w salonie samochodowym, a klient powiedział, że chce pickupa, nie kłóciłbym się z nim o to, czy naprawdę potrzebuje pickupa, i nie wypytywałby go o to, czego się spodziewa. Sprzedałbym mu furgonetkę.

Okej, są chwile, kiedy klienci mówią, że chce i czego naprawdę potrzebuje, są tak daleko od siebie, że staram się z nim omówić tę sprawę, może przekonać go, by zgodził się na coś bardziej racjonalnego. Czasami to działa, czasem nie. Ostatecznie, jeśli nie mogę zmienić zdania, daję mu to, czego chce. Jeśli wróci później i powie: „Och, to naprawdę nie spełniało moich wymagań biznesowych, możemy obciążyć go więcej za to, co powiedzieliśmy mu za pierwszym razem. To, ile możesz negocjować z klientem, zależy od tego, jak bardzo ufa on twojej wiedzy, w jaki sposób jego umowa z tobą pasuje do organizacji, i, szczerze mówiąc, jak bardzo są byki.

Byłby to bardzo rzadki przypadek, w którym, zakładając, że to ode mnie zależy, straciłbym kontrakt, ponieważ uważałem, że wymagania były źle pomyślane.

Pamiętaj, że osoby, z którymi negocjujesz Twoja firma, mogą, ale nie muszą wymyślić tę zasadę 25%. Może to być reguła narzucona im z góry.

Widzę pięć możliwych odpowiedzi:

Jeden. Przekonaj swojego szefa lub osobę negocjującą z klientem, aby się o to spierać. Szanse są, że to nic nie da, ale możesz spróbować.

Dwa. Odmów tego. Prawdopodobnie spowoduje to zwolnienie z pracy lub, jeśli firma się z tobą zgodzi, spowoduje utratę umowy. To wydaje się bezproduktywne.

Trzy. Napisz bezużyteczne komentarze, aby wypełnić miejsce, takie komentarze, które powtarzają tylko to, co jest w kodzie i które każdy programista zdolny do modyfikacji kodu zobaczy w ciągu 2 sekund. Widziałem wiele takich komentarzy. Wiele lat temu pracowałem dla firmy, w której musieliśmy umieszczać bloki komentarzy przed każdą funkcją, która wymieniała parametry, takie jak:

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

Zarzut, że takie komentarze stanowią obciążenie konserwacyjne, ponieważ musisz je aktualizować, jest nieważny. Nie ma potrzeby aktualizowania ich, ponieważ żaden poważny programista nigdy na nich nie spojrzy. W przypadku jakichkolwiek pytań należy wyjaśnić wszystkim członkom zespołu, że bezużyteczne, zbędne komentarze należy zignorować. Jeśli chcesz wiedzieć, jakie są parametry funkcji lub co robi linia kodu, przeczytaj kod, nie patrz na bezużyteczne komentarze.

Cztery Jeśli chcesz dodać zbędne bezwartościowe komentarze, być może warto poświęcić czas na napisanie programu do ich wygenerowania. Coś z inwestycji z góry, ale może zaoszczędzić sporo pisania na maszynie.

Kiedy zaczynałem w tym biznesie, firma, dla której pracowałem, korzystała z programu reklamowanego jako „Zapisuje dla ciebie dokumentację! Kompletna dokumentacja dla każdego programu!” System wymagał, abyśmy nadali wszystkim zmiennym w zasadzie bezsensowne nazwy, a następnie mieli tabelę podającą sensowną nazwę dla każdej zmiennej, więc w zasadzie to, co zrobiła „automatyczna dokumentacja”, zastąpiła bezsensowną nazwę, którą zmusiła nas do użycia znaczącą nazwą. Na przykład - działało to z COBOL - miałbyś w swoim programie wiersz, który powiedział:

MOVE IA010 TO WS124

i wygenerowaliby wiersz „dokumentacji”, który powiedział

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

W każdym razie można z pewnością napisać program, który dość łatwo wygeneruje równie bezwartościową dokumentację. Przeczytaj wiersz jak

a=b+c

i wygeneruj komentarz

// add b to c and save result in a

Itp.

Pięć. Jak najlepiej wykorzystaj tę głupią zasadę. Spróbuj pisać użyteczne i znaczące komentarze. Hej, to może być dobre ćwiczenie.

Aha, nawiasem mówiąc, dodam, że zawsze można zagrać w metrykę.

Pamiętam, gdy jeden z pracodawców powiedział, że zacznie mierzyć produktywność programistów na podstawie liczby wierszy kodu, które produkowaliśmy tygodniowo. Kiedy powiedziano nam to na spotkaniu, powiedziałem: Świetnie! Mogę z łatwością zwiększyć swój wynik. Nigdy więcej pisania

x=x+4;

Zamiast tego napiszę:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

Pętle Zapomnij, skopiuję i wkleję kod dziesięć razy. Itp.

Więc tutaj, jeśli mają policzyć wiersze komentarzy, skróć każdy wiersz i kontynuuj pomysł w następnym wierszu. Jeśli nastąpi zmiana w komentarzach, nie aktualizuj istniejącego komentarza. Wpisz datę, a następnie skopiuj cały tekst i napisz „Zaktualizowano” i nową datę. Jeśli klient zadaje to pytanie, powiedz mu, że uważasz, że konieczne jest zachowanie historii. Itd itd.

Sójka
źródło
2

Arbitralne wskaźniki wydają się być faktem w zbyt wielu projektach ...

Jest to często widoczne w głupich wymaganiach, takich jak maksymalna złożoność Cyclomatic prowadząca do bardziej złożonego kodu, ponieważ funkcje są niepotrzebnie dzielone w celu zapewnienia zgodności lub pliki są dzielone, ponieważ przekraczają pewną dowolną długość SLoC

Komentarze powinny dodawać do kodu i wyjaśniać, co się dzieje (a nie tylko powtarzać kod!).

To powiedziawszy, jeśli tego właśnie chce Twój klient, a Twoja firma zgodziła się to zapewnić, chyba że Twój kierownik ds. Kontroli jakości opracuje dawkę zdrowego rozsądku, utkniesz.

Andrzej
źródło
Tak. Arbitralne reguły powodują, że ludzie modyfikują swoje zachowanie, aby skorzystać z reguły. To jest problem biurokracji. Zaskakuje mnie, jak ludzie mogą wymyślić regułę i nie uważają, że ludzie, których ta reguła dotyczy, mogą wziąć to pod uwagę przy podejmowaniu decyzji, co robić. Potem wprowadzają więcej zasad, aby zatkać luki, i więcej zasad, aby zatkać luki utworzone przez luki itp.
Jay
2

W krótkim okresie nie można tak naprawdę nic zrobić. Idź z tym.

Powinieneś także zignorować wszystkie głupie pomysły, które widzę w tym wątku na temat pasywnych agresywnych protestów i głupich żartów w kodzie.

Gdy rozwiniesz relację zaufania z klientem, będą oni lepiej przygotowani do wysłuchania twojego rozumowania - może się okazać, że jest to głupie żądanie jednej osoby, która kiedyś miała wpływ i że ma bardzo małe wsparcie wewnętrzne.

W żadnych okolicznościach nie powinieneś przeciwstawić się temu bez zgody klienta.

Gburton
źródło
2

Jestem rozczarowany brakiem wyobraźni moich kolegów programistów tutaj.

Wydaje mi się, że klient przeprowadził pewne badania. Być może gdzieś przeczytał, że kod jakości zwykle zawiera około 25% komentarzy. Oczywiście dba / martwi się o utrzymanie w dalszej części drogi. W jaki sposób czyni to konkretnym w dokumencie wymagań, który ma być związany z umową? To nie jest łatwe. Może to nawet być niemożliwe. Jednak chce się upewnić, że uzyska wartość za swoje pieniądze, więc wymienia pewne wskaźniki jakości.

To wcale nie brzmi dla mnie głupio ani śmiesznie. Ludzie, którzy napisali wymagania, najprawdopodobniej nie są programistami. Być może mieli złe doświadczenia z wcześniejszym projektem. Ich konserwatorzy narzekają: „Żadne z tych gówna nie jest udokumentowane!”. Dzwoni w uszach, gdy piszą nowe wymagania do następnego projektu.

Jeśli poważnie myślisz o udokumentowaniu swojego kodu i zapewnieniu kontekstu dla grupy zajmującej się utrzymaniem, ten wymóg zostanie spełniony automatycznie. Więc nie bądź w tym cipką!

W końcu, czy to 21%, czy 29%, nikogo to nie obchodzi. Klient sprawdzi twoje rzeczy przez niezależnego programistę i lepiej zrozumie, co zrobiłeś.

Martin Maat
źródło
1
Pytanie definitywnie dowodzi, że wyrażenie komentarza jako celu przyniesie odwrót. Byłoby bardziej efektywne, gdyby klient miał cel, że kod musi być zrozumiały dla innego programisty (w zespole? Z zewnątrz? Z jaką wiedzą i umiejętnościami w tle?) I dać 25% jako (elastyczną) wskazówkę. Wyrażenie tego w ten sposób byłoby lepiej zrozumiane przez wykonawców i zachęcało do lepszych alternatyw, takich jak czysty kod.
Christophe
0

Spotkałem wielu programistów, którzy nie rozumieją, jak istnieją ludzie, którzy obecnie nie pracują nad tym projektem.

Dla nich wszystko, co wiedzą, JEST znane wszystkim.

Jeśli ktoś nie wie WSZYSTKIEGO, co obecnie zna, to ci ludzie są dla niego „idiotami”.

Za pomocą tego standardu możesz zmusić ludzi do nawyku pisania komentarzy.

Mogą pisać bezużyteczne komentarze w 99% przypadków, ale czasami mogą faktycznie zapisać jedną z rzeczy, które „KAŻDY WIEDZA”, a ktoś nowy w zespole może nie spędzić 16 godzin na poszukiwaniu błędu (który ktoś już rozwiązał, ale potem cofnięto go z innego powodu), co byłoby oczywiste z komentarzem w tym punkcie kodu.

Komentarze na liniach z nieoczywistymi błędami mogą również pomóc przyszłym programistom całkowicie przypadkowo złamać program (szczególnie, gdy część „zepsucia” nie jest oczywista podczas szybkiego testu).

Mam nadzieję, że jest pomocna
źródło
3
Problem z wpuszczeniem 10000 małp na maszyny do pisania nie polega na tym, że nigdy nie piszą czegoś cennego, ale że tych znikających rzadko klejnotów trudno znaleźć na stosie śmieci.
Deduplicator