Czy zapisywanie notatek, myśli, algorytmów, decyzji podczas kodowania i konserwacji jest normalne / dopuszczalne? [Zamknięte]

22

Niektórzy ludzie mają ten problem, że nie mogą myśleć bez słów. A spisanie ich myśli i decyzji jest najskuteczniejszym sposobem postępowania.

Więc - czy to normalne i dopuszczalne, że zapisuję swoje myśli i decyzje w pliku Notepad ++ podczas kodowania?

Czasami powinno to być dopuszczalne, np. Przy odtwarzaniu dokumentacji technicznej lub wnioskowaniu na temat bardziej złożonych algorytmów, ale czasem może być dziwne, np. Kiedy rozważam opcje projektowania i próbuję dokonać oceny.

Wpływ tej praktyki na wydajność jest niejasny. Z jednej strony - rozumowanie za pomocą wewnętrznych słów może być szybsze niż za pomocą słów pisanych. Z drugiej strony - bardziej złożone problemy wymagają pisania. Poza tym, jeśli utkniesz z większą liczbą opcji projektowych, to uczucie jest lepsze, gdy decyzja jest zapisana, więc podnosi morale.

Do Pana
źródło
5
Ja też to robię i ogólnie tego żałuję, gdy tego nie robię. Naprawdę pomocne jest, aby później spojrzeć w przeszłość, aby zapamiętać, dlaczego zrobiłeś coś w określony sposób, lub móc podjąć decyzję później, gdy nie zagłębisz się głęboko w wizję tunelu. Kiedy zapominam coś zanotować, zwykle zapominam dlaczego, a potem spędzam więcej czasu na śledzeniu moich kroków.
PseudoPsyche
21
Czuję, że brakuje nam części kontekstu? Czy to spostrzeżenie dotyczyło skargi dotyczącej wydajności? Często krytyka zawiera sugestie dotyczące pierwotnej przyczyny, która może, ale nie musi być istotna.
Jim Rush
9
„Komentarze i dokumentacja” muszą być zapisane w kodzie źródłowym i przechowywane. Twoje przemyślenia na temat rozważenia opcji projektowych mogą zostać zapisane, ale zazwyczaj nie są przechowywane, to jest rzeczy, które rzadko ci pomogą później (możesz zachować notatki na temat wyników tego procesu myślowego, jeśli nie jest to jasne z samego kodu źródłowego, ale nie o to pytałeś). Jeśli wolisz formę elektroniczną, ołówek i papier, lub jeśli możesz to wszystko zrobić w głowie, to zależy od ciebie, nikt inny, ale możesz powiedzieć ci, co jest dla ciebie najlepsze.
Doc Brown
4
... PS: Zazwyczaj wolę ołówek i papier lub białą tablicę do tych rzeczy i myślę, że nie stałbym się lepszym programistą, gdybym próbował zrobić to wszystko w mojej głowie, wręcz przeciwnie.
Doc Brown
7
Dlaczego nie byłoby to dopuszczalne? Do przyjęcia dla kogo?
Paul D. Waite,

Odpowiedzi:

62

To nie tylko normalne, to dobry pomysł.

Jest słynny cytat

„Daj mi sześć godzin na ścięcie drzewa, a pierwsze cztery spędzę na ostrzeniu siekiery”.

Poświęcenie czasu na uporządkowanie myśli i zaplanowanie pracy przed kodowaniem to czas dobrze spędzony. Zapisanie tych myśli na papierze da ci czas na zastanowienie się nad swoimi planami, ich krytykę i uporządkowanie w sposób, który byłby bardzo trudny, gdyby wykonano je tylko „w twojej głowie”.

Dan Pichelman
źródło
8
To dobry cytat, chociaż usunę błędne przypisanie. quoteinvestigator.com/tag/abraham-lincoln
Paul Draper
1
Z pewnością prawdziwe stwierdzenie i dobry cytat, ale w moim rozumieniu pytanie ma inne znaczenie. O ile rozumiem, PO nie ma wątpliwości co do znaczenia planowania z wyprzedzeniem. Pyta, czy bardziej efektywne jest zapisywanie tych myśli / planowanie w dół, czy po prostu trzymanie ich wszystkich tylko w głowie.
Doc Brown
2
Uważaj, że godzina ostrzenia jest więcej niż wystarczająca. To zadanie powinno być oszacowane na maksymalnie 3 godziny, ale luz został wydany na bezcelowe nadmierne przygotowanie. Jaka była moralność? ;-)
Steve Jessop
26

Tak, jest to całkowicie dopuszczalne i normalne.

Dokumentowanie procesu decyzyjnego jest często cenne przy ponownym odwiedzaniu kodu, aby pomóc ustalić, dlaczego kod został napisany w określony sposób.

Te uwagi mogą być zawarte bezpośrednio w kodzie jako komentarze, jeśli są wystarczająco krótkie. Rozszerzony komentarz jest często przechowywany jako część zewnętrznego dokumentu projektu technicznego.

McKnz
źródło
4
Chciałbym mocno zalecamy nie zawierać notatki o rozważa możliwości projektowania i próbuje dokonać osądu jako komentarze w kodzie źródłowym, te nigdy nie są „wystarczająco krótki”. Tylko ostateczne wyniki tego procesu myślowego, ale to zupełnie inne od tego, o co prosił PO.
Doc Brown
3
Często dyskutuję na temat „dlaczego podjęliśmy tę decyzję”. Niezwykle pomocne jest powrót do moich codziennych notatek z projektu, aby podać kontekst, w tym omówione alternatywy. Myślę, że jestem w dobrym towarzystwie: według The Everything Store Jeff Bezos robi to samo.
kdgregory
8
@DocBrown - czasami jest to dobry pomysł, aby to powody, dla których nie nie korzystają z innych możliwych metod / algorytmów więc deweloper przyszłość nie będzie starał się zastąpić to, co zrobiłeś
HorusKol
1
@HorusKol: w niektórych rzadkich przypadkach jest to trywialny zdrowy rozsądek. Jest to jednak zupełnie odmienne od „dokumentowania procesu decyzyjnego” .
Doc Brown
1
@DocBrown racja, nie sądzę, że ktoś chce stron notatek w kodzie źródłowym. :)
mcknz
20

To cholernie dobry pomysł. Aż do momentu, gdy stanie się sposobem na zwlekanie.

Kluczem jest równowaga. Uważam, że jestem najbardziej produktywny, jeśli nie zapakuję się w siebie, ale będę wychwytywać pomysły w miarę ich pojawiania się.

Jeśli grinduję na niskim poziomie i pojawia się pomysł na wysokim poziomie, po prostu zapisuję go i wracam do niego później.

Planowanie pracy jest dobrym pomysłem, ale chyba że musisz się komunikować lub zaprezentować publiczności, najlepszym narzędziem są pióro i serwetka. Uchwyć pomysł. Nie trać czasu na upiększanie.

candied_orange
źródło
Markdown to kolejny świetny sposób na robienie tych notatek. Trzyma ręce na klawiaturze, więc proces myślowy jest minimalny.
RubberDuck
1
Niezależnie od tego, czy uruchomisz edytor, czy złapiesz długopis i serwetkę, lepsza alternatywa zależy wyłącznie od twoich osobistych umiejętności pisania na klawiaturze i pisania odręcznego. Dla mnie lepszym rozwiązaniem jest oczywiście edytor.
cmaster
9

W każdej sytuacji zawodowej jest to nie tylko „normalne i dopuszczalne”, jest obowiązkowe. Typowy cykl programowania składa się z dwóch faz dokumentacji, zanim jeszcze rozpocznie się kodowanie:

  1. Dokument wymagań funkcjonalnych: zazwyczaj napisany przez analityków biznesowych, określający funkcjonalność, która ma zostać zaimplementowana.

  2. Szczegółowy projekt dokumentu: który jest właściwie tym, o czym mówisz, tylko bardziej formalny, określający rozkład funkcjonalny (faktoring) systemu, algorytmy itp. Niektóre z moich (bardzo) starych są w trybie online, np . To .

W przypadku mniej formalnej dokumentacji 110% zgadzam się z wcześniejszymi uwagami na temat komentarzy wewnętrznych. To jedyna droga; tak czy inaczej, wszystko inne w końcu się gubi. Ale schludne i przemyślane komentowanie w wierszu to osobna umiejętność kodowania, rozwijana poprzez wysiłek i praktykę, jak każda inna umiejętność. Możesz zobaczyć niektóre z moich (bardzo) starych rzeczy, np . To . Ten styl może ci się nie podobać. Polecam najpierw znaleźć dobrze skomentowany kod w stylu, który ci się podoba, i emulować go we własnym kodzie. Po chwili dostosuj go według własnego uznania.

John Forkosh
źródło
4

Świetnym miejscem na umieszczenie tego rodzaju informacji jest bezpośrednio w komunikacie zatwierdzenia systemu kontroli wersji (SVN, git itp.). W ten sposób możesz zobaczyć zmiany i ich uzasadnienie w tym samym miejscu.

Derek
źródło
1
Umożliwia to również ich wyszukiwanie. Możesz wyszukiwać komunikaty zatwierdzenia w wierszu poleceń git i sourcetree, np. Jeśli używasz notatnika, najprawdopodobniej pliki nigdy się nie otworzą i są trudne do wyszukiwania bez znajomości obszernego basha i pisania skryptu, który przeszukuje wszystkie odpowiednie miejsca.
Mam nadzieję, że będzie
Próbuję to zrobić zarówno w moich instrukcjach zatwierdzania, jak i w żądaniu błędu lub funkcji z linkami do zatwierdzenia. Robię też datowane komentarze w kodzie z powodów, dla których zmieniłem kod. Pomaga to znacznie w naszej skrzypiącej starej bazie kodu, w której komentarze są w dużej mierze nieznane.
delliottg
Nie, to coś innego. Komunikaty zatwierdzania powinny opisywać co zostało zrobione, a nie dlaczego. Powód, dla którego wpisuje się w komentarzach do dokumentacji, dołączonej dokumentacji i rozwiązaniu problemu z śledzeniem problemów. Nie możesz umieścić pięciu stron notatek i pracy projektowej w komunikacie zatwierdzenia, ani nie powinieneś tego chcieć.
Lekkość ściga się z Moniką
Wspaniale jest umieścić go w systemie kontroli wersji. Lepszym miejscem jest jednak zwykły plik tekstowy. Są łatwiejsze w użyciu niż zatwierdzanie wiadomości.
Thorbjørn Ravn Andersen
2

Oprócz innych dobrych odpowiedzi dodam, że często zapisuję swoje przemyślenia na temat tego, co próbuję zrobić.

Wyrażanie się w wyrażaniu tego, co próbuję zrobić, pomaga mi w realizacji założeń, założeń i / lub wymagań, które niekoniecznie się spełniają.

To wskazuje na alternatywne rozwiązania, które z kolei mogę lepiej przemyśleć; to pisanie pomaga uratować moje miejsce, jeśli pomyślę o czymś innym.

Robię szybkie notatki, aby zbadać oddech i głębię, więc działa rekurencyjnie, pomagając mi opracowywać, nawigować i oceniać drzewo rozwiązań, tworzyć kopie zapasowe, eksplorować, odkrywać, realizować i podejmować decyzje.

Erik Eidt
źródło
1

Zapisywanie wszystkiego, co może zaoszczędzić czas / (nowych) członków zespołu, to czas, który dobrze spędzasz. Tylko upewnij się, że jest to coś, czego ktoś może potrzebować później i nie zastanawiaj się, chyba że jest to naprawdę długoterminowy projekt.

Nie powinno to również zająć czasu. Jeśli spędzasz czas na myśleniu, możesz zapisać swoje przemyślenia od 1 do 1 (o ile będą one / mogą być dla kogoś przydatne).

Prawdziwym problemem może być przemyślenie tego, co piszesz. To, że piszesz, nie oznacza, że ​​musisz przestrzegać już istniejącego formatu lub przejść całą procedurę tworzenia pełnej dokumentacji.

Jeśli wybierzesz między nie zapisywaniem niczego a pisaniem nieformalnych notatek w notatniku, po prostu napisz nieformalne notatki.

Mam nadzieję, że jest pomocna
źródło
1

Mówicie: „Niektórzy ludzie mają ten problem, że nie potrafią myśleć bez słów. A spisanie myśli i decyzji jest najskuteczniejszym sposobem na kontynuację”.

Jeśli spisanie myśli i decyzji jest najskuteczniejszym sposobem postępowania, dlaczego nie byłoby normalne i dopuszczalne, aby postępować w najbardziej efektywny sposób? Robisz to, co dla Ciebie najlepsze. Może nie być to, co działa najlepiej dla kogoś innego. W takim przypadku nie pozwalasz komuś innemu powiedzieć, co jest dla Ciebie najlepsze, i nie mówisz mu, co jest dla niego najlepsze. Każdy robi to, co dla niego najlepsze.

gnasher729
źródło
1

Ludzie mogą jednocześnie trzymać w głowie tylko siedem „rzeczy”. To jest powód dla siedmiocyfrowych numerów telefonów. Aby programiści mogli efektywnie pracować, muszą znaleźć jakiś system, który odciąży rzeczy z pamięci i szybko je w razie potrzeby w razie potrzeby odzyska. Robienie notatek jest oczywistym i bezpośrednim sposobem, ale każdy, kto pracuje nad czymś umiarkowanie złożonym, musi to jakoś zrobić . Po sparowaniu programu z kimś, poszukaj jego metody.

Jednym z powszechnych sposobów jest rozwój oparty na testach. W tej metodologii piszesz jeden test zakończony niepowodzeniem, piszesz wystarczającą ilość kodu, aby przejść ten test zakończony niepowodzeniem, a następnie poprawiasz kod, aby wyglądał ładniej, zachowując wszystkie istniejące testy. Ta metodologia utrzymuje wszystkie „notatki” zakodowane w testach. Ludzie mogą w ten sposób pracować bardzo szybko, nie robiąc notatek, ponieważ koncentrują się na kolejnym teście.

Innym powszechnym sposobem jest po prostu zapisywanie notatek w kodzie jako komentarzy lub kodów pośredniczących, a następnie stopniowe zastępowanie ich prawdziwymi. Tak zwykle piszę algorytmy. Mój pierwszy szkic jest tylko główną funkcją z pseudokodem, a następnie stopniowo wypełnia coraz głębsze poziomy abstrakcji.

Nie przejmuj się używaniem dowolnej metody, ale spróbuj zauważyć, jakich metod używają Twoi „wydajni” koledzy. Mają te same ludzkie ograniczenia, co ty.

Karl Bielefeldt
źródło
1
TDD to ćwiczenie do robienia notatek? Nie wydaje mi się
Robert Harvey