Czy są jakieś powszechne praktyki komentowania wyrażeń regularnych: komentarze wstawiane odnoszące się do innej części RegEx lub komentarze ogólne dla wszystkich wyrażeń?
documentation
coding-style
comments
m0nhawk
źródło
źródło
Odpowiedzi:
Moim zdaniem dobrą praktyką jest zwięzłe stwierdzenie w komentarzach, jaka jest ogólna idea wyrażenia regularnego. Oszczędza to innym programistom (lub czasem samemu) problemów z kopiowaniem i wklejaniem wyrażenia regularnego w parserze takim jak RegExr , tylko po to, aby zrozumieć, co robi.
źródło
Jest to odpowiedź specyficzna dla języka, ale pytanie nie zawiera żadnego języka.
Książka „Dive Into Python” sugeruje implementację komentarzy przy użyciu pełnych wyrażeń regularnych :
Przykład:
Źródło i dalsze szczegóły tutaj
Ta metoda ma niewielką wadę polegającą na tym, że osoba dzwoniąca musi wiedzieć, że wzorzec jest zapisany w pełnym formacie i odpowiednio ją wywołać.
źródło
re.compile
w punkcie, w którym zdefiniujesz wzór, i przechowywać tylko wynikowy obiekt. W ten sposób flagi kompilacji wzorca (w tymre.VERBOSE
) nie muszą być oddzielane od samego wzorca.#
jeśli używam pełnej flagi? Nawiasem mówiąc: linki źródłowe wydają się nie działać.#
można dopasować dosłownie w klasie znaków:[#]
(źródło: docs.python.org/3/library/re.html#re.X )Zazwyczaj napiszę wyrażenie regularne i nie wyjaśnię poszczególnych elementów wyrażenia regularnego, ale raczej jego cel. To jest to, co i dlaczego. To trochę jak pytanie „jak powinny wyglądać moje komentarze?” na które można by powiedzieć: „ Nie pisz, co robi kod, napisz, dlaczego kod robi to, co robi ”
O ile nie próbujesz nauczyć kogoś o wyrażeniach regularnych za pomocą komentarzy w kodzie, nie sądzę, aby wyjaśniać, co zrobi każdy pojedynczy fragment. Pracując z innymi programistami, możesz bezpiecznie założyć, że znasz coś jako globalne wyrażenia regularne.
źródło
Myślę, że to naprawdę zależy od tego, jak składasz regex razem. Ogólnie rzecz biorąc, myślę, że złym pomysłem byłoby umieszczanie komentarzy w samym łańcuchu wyrażeń regularnych (o ile wiem, nie jest to możliwe w większości scenariuszy). Jeśli naprawdę chcesz skomentować określone fragmenty wyrażenia regularnego (próbujesz kogoś nauczyć?), To podziel każdy fragment na osobne ciągi w swoich liniach i skomentuj każdą linię, używając normalnego procesu komentowania w języku programowania. W przeciwnym razie odpowiedź pleinolijf jest całkiem dobra.
przykład:
źródło
Zwykle definiuję stałą łańcucha, której nazwa opisuje ogólny cel wyrażenia regularnego.
Na przykład:
Możesz dodać komentarz powyżej tej stałej, aby podać jej opis, ale zwykle sama nazwa powinna wystarczyć.
źródło
W niektórych scenariuszach deweloperzy mogą używać wyrażeń regularnych w celu dopasowania tekstu poza typową domeną. Pierwotni programiści mogli przejść wiele iteracji przechwytujących różne przypadki brzegowe, które mogły zostać odkryte tylko w tym procesie iteracyjnym. Zatem kolejni programiści mogą nie zdawać sobie sprawy z wielu przypadkowych przypadków, z którymi pierwotni programiści zajmowali się, nawet jeśli są świadomi ogólnego przypadku.
W takich przypadkach warto udokumentować przykłady zmian. Lokalizacja tej dokumentacji może się różnić w zależności od ilości (np. Niekoniecznie w kodzie).
Jednym ze sposobów podejścia jest założenie, że przyszli programiści będą mieli tylko podstawową wiedzę, na przykład, jak działają wyrażenia regularne, ale nie wiedzę, którą ty (1) posiadałeś przed opracowaniem wyrażeń regularnych, które niekoniecznie byłyby znane przyszli programiści lub (2) wiedza zdobyta podczas programowania (np. odkryte przypadki skrajne).
Na przykład, jeśli podczas programowania mówisz coś w stylu „Och, nie wiedziałem, że X może przyjąć tę formę”, warto to udokumentować (i być może część wyrażenia regularnego, która obsługuje tę odmianę).
źródło
Komentarze powinny zawierać przydatne informacje, które nie są oczywiste z kodu.
Istnieje niewiele aplikacji, które potrzebują każdego ostatniego cyklu, jeśli dopasowujesz wzorce do ogromnych zestawów danych, być może istnieje lepszy sposób, a może nie, ale w większości przypadków dodatkowy czas wykonania nie jest tak duży.
I pamiętaj, że następną osobą, która natknie się na twój kod i naprawisz błąd, możesz być ty za sześć miesięcy i nie ma możliwości, abyś zapamiętał, co powinien zrobić.
źródło
Wyodrębnij RegEx do osobnej klasy do znaczącej nazwy. Następnie udokumentowałbym kod za pomocą automatycznych testów.
To zapewni
Oczywiście twoja klasa może obsługiwać kilka wyrażeń regularnych.
źródło