Czy piszesz tytuły w komentarzach do kodu? [Zamknięte]

Przeglądałem stary kod, który napisałem (pierwszy rok na uniwersytecie) i zauważyłem, że pisałem tytuły komentarzy poprzedzające różne części kodu. Rzeczy takie (pochodzi z gry Monopoly):

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

Może to być zbędne i prawdopodobnie niepotrzebne, jeśli kod jest naprawdę bardzo przejrzysty, ale gdy skanowałem plik, zaskoczyło mnie, jak mocno czułem się, jakbym wiedział, co się dzieje, chociaż prawie nie patrzyłem na rzeczywisty kod. Zdecydowanie widzę to jako pasujące w pewnych okolicznościach, więc zastanawiam się - czy to robisz? Czy uważasz, że to dobry pomysł? A może to za dużo?

To zapach kodu. To mówi co, a nie dlaczego .

Jeśli jest to konieczne, podziel kod na małe funkcje.

Robię to cały czas. Zarówno do zaznaczenia, co robi kod, jak i, co ważniejsze, jak powiedziałeś, aby ułatwić skanowanie i znalezienie fragmentu kodu. Czasami również zapiszę zaangażowany proces w komentarzach i „wypełniam” kod pod komentarzami, gdy idę.

Interesujące jest dla mnie to, ilu ludzi nie lubi tej praktyki, ale tak naprawdę nie jestem w stanie wyjaśnić, dlaczego. Powodem, dla którego takie komentarze są niezadowolone, jest to, że naruszyłeś zasadę pojedynczej odpowiedzialności. Ta konkretna nazwa jest zwykle używana tylko w kontekście OO, ale ogólna koncepcja jest również nazywana spójnością i ma zastosowanie do innych paradygmatów. Szkoły zazwyczaj nie uczą tego rodzaju zasad projektowania do końca programu studiów, jeśli w ogóle. W rzeczywistości niektórzy nauczyciele nakazują jej naruszenie, aby ułatwić ocenę, wrzucając wszystko do jednego pliku. Dlatego twoja ignorancja na pierwszym roku jest usprawiedliwiona, a fakt, że zauważyłeś „coś” źle i starałeś się wyjaśnić za pomocą komentarzy, jest nawet chwalebny w danych okolicznościach, ale ogólnie lepiej jest naprawić niejasny projekt niż próbować opisać to komentarzem.

Patrzę na te rzeczy jako sposób na uczynienie kodu bardziej przejrzystym czy nie. Jeśli można powiedzieć na podstawie tych metod w pliku co każda część jest wówczas nie ma potrzeby, jednak jeśli mają mieć kilka odcinków to może być użyteczne. Być może, gdy plik kodu staje się zbyt duży, należy go rozbić, co może zmniejszyć potrzebę takich komentarzy.

Powiedziałbym, że jeśli pracujemy w zespole nad opracowaniem standardu, abyście wszyscy przynajmniej kodowali i komentowali w ten sam sposób, dzięki czemu patrzenie na kod staje się łatwiejsze.

Robię to, ponieważ często komunikuję sobie zamiar lub zasadniczo zakładam wygodną zakładkę do rzeczy takich jak „Czyszczenie danych zaczyna się tutaj”. Zazwyczaj pod tym tytułem znajduje się krótkie przypomnienie logiki tego, co robię i dlaczego.

Lubię redundancję. Jeśli z jakiegoś powodu zgubię notatnik laboratoryjny lub będę musiał ponownie przeczytać kod, który napisałem lata temu, nie lubię dzielić tego, co robiłem i dlaczego. Jeśli przynajmniej część tej logiki znajduje się w kodzie, jest ona wystarczająco udokumentowana, abym mógł przynajmniej z nią ponownie pracować.

Myślę, że część moich skłonności do tego jest spora część mojego programowania ma charakter statystyczny, a zatem nieco powtarzalny. Podczas gdy może istnieć kilka fragmentów kodu, w których mam pomocnie nazwaną funkcję do wyszukiwania, mogę mieć kilkadziesiąt dość podobnych zastosowań czegoś takiego jak ogólna funkcja modelu liniowego. Przydaje się możliwość znalezienia, który z nich był „jak wrażliwy jest wynik na kod Choice A vs. Choice B lub C”, a który był czymś innym. Często przyspieszają to tytuły.

Myślę, że jest to przydatne w sytuacjach, w których masz gigantyczne pliki źródłowe z dziesiątkami funkcji i możesz luźno uporządkować je w takie fragmenty. Nie twierdzę jednak, że podoba mi się to lepiej niż mniejsze, bardziej ukierunkowane pliki źródłowe ...