Najlepsze podejście do komentowania kodu źródłowego w celu zrozumienia przepływu pracy całego projektu?

Question

w prywatnych i firmach to wciąż jest problem, który ja lub my, programiści, komentujemy w rzeczywistości nasz kod, ale generalnie nikt nie wie dokładnie, jak działa kod całego projektu. Kiedy piszę własny kod, a projekt jest coraz większy, czasami mam ten problem. Chociaż piszę mnóstwo komentarzy, po 3 miesiącach nie wiesz, co dokładnie robi, to znaczy, jak różne metody i klasy współpracują ze sobą.
Jak rozwiązać ten problem w firmie lub prywatnie (jeśli projekt ma tylko charakter marginalny i nie wymaga specyfikacji wymagań). Czy zawsze masz tak dobry rozwój projektu dzięki dokumentom kontraktowym i specyfikacji wymagań, że nie musisz się tym martwić?

Answer 1

Code complete potrafi wyjaśnić rozwiązanie twojego problemu lepiej niż kiedykolwiek mogłem.

Answer 2

Uważam, że najlepszym sposobem rozwiązania tego problemu jest napisanie testu funkcjonalnego za pomocą platformy testów jednostkowych.

W teście funkcjonalnym piszesz test, który ładuje kilka, jeśli nie wszystkie, podstawowe komponenty. To pokazuje, że wszystkie komponenty działają poprawnie razem, ale otrzymujesz także dokumenty, które pokazują w jednym miejscu, jak wszystko się łączy.

W zależności od tego, jak złożone są interakcje, możesz nie być wystarczający i musisz to udokumentować. Osobiście wolałbym, aby kod był prosty, tak aby jego dokumentacja nie była naprawdę potrzebna lub względnie łatwa do wytłumaczenia.

Jeśli dokumentowanie to brzmi zbyt mocno, jego czas na refaktorowanie kodu tak, aby nie był.

Answer 3

Nie spiesz się, twórz krótkie i proste dokumenty projektowe, dodaj schematy UML, aby pokazać podstawowe idee stojące za całą aplikacją. To dałoby nowym graczom drużynowym szybki przegląd. Opublikuj tę dokumentację na wewnętrznej wiki i zachęć zespół do ulepszenia, jeśli to konieczne.

Następnie, jak zasugerował Peter, niektóre dobrze udokumentowane przypadki testowe naprawdę pomagają: Przeczytaj kod testowy i naucz się korzystać z API. (i, jako efekt wtórnego, przetestuj kod ;-))

Nie będę wkładał zbyt dużo wysiłku w komentarze, szczególnie w komentarzach na linii. Zwykle stają się przestarzałe, ponieważ żaden test jednostkowy nie sprawdza, czy komentarze linii są nadal aktualne, a nawet, że nikt nigdy nie usuwa niepotrzebnych komentarzy.

Answer 4

Dobre pytanie. Część tego, o co pytasz, dotyczy możliwości konserwacji kodu. Moim zdaniem dwóch głównych rzeczy, które można zrobić, aby poprawić ten to: -

• napisać dokumentację projektową
• Develop w utrzymaniu i jasno napisany kod

Z dotychczasowych doświadczeń pierwszy element jest bardzo często zaniedbane w projektach oprogramowania ze względu na ograniczenia czasowe, ale myślę, że jeśli możesz stworzyć przynajmniej schemat klasowy swojego systemu, to jest to o wiele warte, jeśli chodzi o zrozumienie, w jaki sposób obiekty wchodzą w interakcje, gdy w ciągu kilku miesięcy ponownie przejrzysz kod. W zależności od złożoności przydatne mogą być również diagramy sekwencji. Opracowanie tej dokumentacji przyniesie również korzyści nowym członkom zespołu, dzięki szybkiemu przeglądowi struktury oprogramowania.

Nie mogę wystarczająco podkreślić znaczenia pisania jasnego i możliwego do utrzymania kodu.Moje oczy zostały niedawno otwarte po przeczytaniu Clean Code przez Roberta Martina. Jesteś winien sobie i swoim współpracownikom, aby przeczytali przynajmniej pierwsze rozdziały w tej książce. Już samo to natychmiast poprawi czytelność i łatwość obsługi Twojego kodu.

Chodzi o to, że kod powinien brzmieć niemal jak opowiadanie, w którym metody podążają w logicznej kolejności, są krótkie, odpowiednio nazwane i przyjmują kilka parametrów. Wykonanie tego prawie eliminuje potrzebę komentowania kodu i poprawia strukturę kodu.