Co powinno być w dobrym (czytaj: przydatnym) standardzie kodowania?
Odpowiedzi:
Powody każdego wymagania. W ten sposób przestrzeganie standardu nie staje się kultem ładunków, a ludzie wiedzą, że można zmienić standard, jeśli jego przyczyna już nie obowiązuje, lub naruszać normę w szczególnych przypadkach, w których powód wyraźnie nie ma zastosowania. .
Tabs vs Spaces! Dostaję szalone aktualizacje, gdy jeden z moich kolegów przez przypadek popycha wiele tabulatorów do spacji przesuwanych do repozytorium
Konwencje nazewnictwa
EDYCJA: Rozumiem przez to Nazewnictwo Wytyczne, a nie Nazewnictwo Reguły.
Na przykład Wytyczne byłyby All boolean values should begin with Is/Can/Has/etc when possible. Zasada byłabyAll boolean values must start with Is
IsCanUpdatei IsHasChildren. Jasne, to źle, ale zostało to określone w standardzie. I o to mi chodzi: kiedy zaczniesz sprecyzować te rzeczy, musisz upewnić się, że obejmujesz wszystkie podstawy, w przeciwnym razie ludzie napotkają coś, czego standard nie obejmuje lub źle obejmuje, a następnie albo napiszą coś złego, lub zaczną ignorować standard. Tak czy inaczej, zespół przegrywa.
Standard kodowania dla grupy powinien zawierać opcje kompilatora dla ostrzeżeń i błędów, które należy rozwiązać.
Programiści powinni mieć swobodę zwiększania ostrzeżeń dla własnego kodu, ale musi istnieć poziom bazowy, aby czytanie i praca z kodem innej osoby nie zaśmiecały wyników uzyskiwanych z kompilatora.
Taki standard musiałby również określać, w jaki sposób programiści mogą wyłączać takie ostrzeżenia dla poszczególnych przypadków, gdyby istniał wyjątkowy fragment kodu, który w innym przypadku nie byłby zgodny.
Niektóre standardy mi się podobają (wiem, że jest ich dużo, ale takie właśnie preferuję):
Standardy kodowania pomóc trochę podczas pisania kodu po raz pierwszy, one pomóc dużo gdy ty lub twój wymiana, musi 2 lata później zaktualizować kod.
Idealny standard prowadzi do kodu, w którym można przejść do dowolnej dowolnej strony w kodzie i dokładnie zrozumieć, co robi przy pierwszym czytaniu, ponieważ
Z drugiej strony zbyt wiele arbitralnych standardów może zakłócać przepływ pisania kodu. Uważam więc, że każdy element proponowanej konwencji kodowania powinien zostać oceniony na podstawie tych 2 kryteriów:
Jeśli żadna z nich nie jest prawdziwa, przedmiot jest po prostu arbitralny i prawdopodobnie niepotrzebny
Do standardowego pisma dołączam następujące rzeczy:
Dla jasności:
Organizacja plików: Określenie stałej kolejności elementów w pliku pozwala zespołowi łatwo nawigować po innych plikach. Nie powinieneś polować, aby znaleźć #defines lub definicje struktur.
Konwencje nazewnictwa: Spójne nazewnictwo poprawia czytelność. Ale unikaj przesadnego określania zbyt wielu reguł, które szkodzą zapisywalności.
Struktura kodu. Umieszczenie nawiasów klamrowych, poziomy wcięcia, spacje vs tabulatory itp. Tak, może to być silna osobista preferencja, ale celem jest jasny kod. Znajdź najlepszą opcję dla zespołu i trzymaj się jej.
Dla poprawności:
Najlepsze praktyki właściwe dla danego typu problemu: Reguły dotyczące alokacji pamięci lub współbieżności lub przenośności.
„Const Correctnesss”, właściwe użycie statici volatileitp.
Reguły dotyczące makr preprocesora i innych łatwo nadużywanych funkcji języka.
Inspirujące, pragmatyczne pomysły, które skłaniają ludzi do myślenia, zamiast negatywnych ograniczeń, które powstrzymują ludzi od myślenia.
W przeciwnym razie dostaniesz małpy kodowe, które boją się iść za bananami .
Co powinno być w standardzie kodowania? Jak najmniej. Mniej raczej więcej. I proszę z uzasadnieniem.
Nie dlatego, że jestem jakimś kowbojskim programistą, który nie chce żadnego procesu, ale dlatego, że widziałem ciężkie specyfikacje kodowania bez logiki poza tym (prawdopodobnie) „Znalazłem to w sieci gdzieś w '95”, co po prostu stało się biurokratyczny koszmar do pracy.
Niektórzy ludzie szczerze wierzą, że po podwyższeniu standardów zauważą odpowiedni wzrost „jakości” kodu i być może dzięki temu osiągną. W międzyczasie będą ignorować architekturę, wydajność, zdrowy rozsądek i kilka innych rzeczy, które w końcu mają znaczenie większe niż liczba linii w pliku.
Jakiś dobry, zdrowy rozsądek nie poszedłby źle; jest o wiele za dużo standardowych dokumentów kodujących, które pracują w nieistotnych punktach (elementy takie jak typ i rozmiar czcionki są jednymi z bardziej ekstremalnych, jakie widziałem).
Najlepszą rzeczą do zrobienia, jeśli jesteś w grupie programistów, jest rozmawianie ze sobą i patrzenie na swój kod, wypracowanie konsensusu co do akceptowalnego i jeśli musisz zapisać główne punkty jako wytyczne, ale zachowaj je jako tylko te wytyczne. Jeśli nie możesz uzasadnić rozbieżności w stosunku do wytycznych, naprawdę powinieneś rozważyć, dlaczego to robisz.
Na koniec dnia przejrzysty i zrozumiały kod jest ważniejszy niż jakakolwiek sztywna zasada dotycząca układu lub typografii.
Jak wspomnieli inni, ważna jest obsługa testów kodu. Lubię też zobaczyć:
Struktura projektu Czy testy są częścią kodu, czy są w osobnym katalogu projektu / pakietu /? Czy kod interfejsu użytkownika działa z elementami zaplecza? Jeśli nie, w jaki sposób jest podzielony na przedziały?
Proces rozwoju. Pisać testy przed kodem? Czy naprawianie uszkodzonych wersji ma pierwszeństwo przed rozwojem? Kiedy wykonywane są recenzje kodu i co powinny one obejmować?
Zarządzanie kodem źródłowym. Co zostaje zameldowane, kiedy? Czy dokumenty projektowe i plany testów są kontrolowane pod kątem poprawek? Kiedy rozgałęziasz się i kiedy tagujesz? Czy zachowujesz poprzednie wersje, a jeśli tak, to ile / na jak długo?
Standardy wdrażania. Jak pakowana jest kompilacja? Co należy znaleźć w uwagach do wydania? W jaki sposób tworzone / kontrolowane / uruchamiane są skrypty aktualizacji?
Zapomnij o tych bzdurach na temat konwencji nazewnictwa, formatowania i liczby wierszy w funkcji / metodzie / module. Jedna zasada: używaj istniejącego stylu w tym, co edytujesz. Jeśli nie podoba ci się czyjś styl, rozróżnij go w recenzji kodu. Jedynym wyjątkiem może być tabulacja w porównaniu do spacji, choćby dlatego, że wielu edytorów / IDE na ślepo konwertuje jeden na drugi, a następnie niszczycie historię zmian, ponieważ każda linia została zmieniona.
Myślę, że w rzeczywistości są dwie rzeczy, którymi należy się zająć, i tak naprawdę rozważyłbym je oddzielnie, ponieważ nie można do nich podejść w ten sam sposób, chociaż uważam, że obie są ważne.
Techniczny aspekt kwalifikuję do standardu kodowania , podobnie jak Herb Sutter i Andrei Alexandrescu z ich standardami kodowania C ++ . Prezentacja, którą kwalifikuję w stylu kodowania , która obejmuje konwencję nazewnictwa, wcięcie itp.
Standard kodowania
Ponieważ jest to czysto techniczny standard kodowania może być w większości obiektywny. W związku z tym każda reguła powinna być poparta uzasadnieniem. W książce, o której mówiłem, każda pozycja ma:
Uzasadnienie i wyjątki są bardzo ważne, ponieważ podsumowują dlaczego i kiedy.
Tytuł powinien być na tyle wyraźny, że podczas recenzji wystarczy mieć listę tytułów (ściągawka) do pracy. I oczywiście pogrupuj elementy według kategorii, aby łatwiej było na nie zwrócić uwagę.
Sutter i Alexandrescu udało się mieć listę tylko stu przedmiotów, mimo że C ++ jest uważany za włochatego;)
Styl kodowania
Ta część jest na ogół mniej obiektywna (i może być wręcz subiektywna). Chodzi tutaj o zapewnienie spójności, ponieważ pomaga to opiekunom i nowym osobom.
Nie chcesz przystępować do świętej wojny o tym, który styl wcięcia lub nawiasu klamrowego jest tutaj lepszy, istnieją na to fora: więc w tej kategorii robisz rzeczy na zasadzie konsensusu> głosowanie większością> arbitralna decyzja przywódcy (przywódców).
Przykład formatowania znajduje się na liście opcji stylu artystycznego . Idealnie byłoby, gdyby reguły były jasne i kompletne, aby program mógł przepisać kod (choć jest mało prawdopodobne, abyś go kodował;))
W przypadku konwencji nazewnictwa starałbym się łatwo odróżnić klasy / typy od zmiennych / atrybutów.
Również w tej kategorii klasyfikuję „miary”, takie jak:
Różne?
I na koniec, jest jeden element, który rzadko, jeśli w ogóle, jest omawiany w Standardach kodowania, być może dlatego, że jest specyficzny dla każdej aplikacji: organizacja kodu. Problem architektoniczny jest chyba najbardziej wybitnym problemem, zepsuć początkowy projekt, a będziesz nim nękać za wiele lat. Być może powinieneś dodać sekcję dotyczącą podstawowej obsługi plików: nagłówki publiczne / prywatne, zarządzanie zależnościami, separacja problemów, współpraca z innymi systemami lub bibliotekami ...
Ale to nic, jeśli nie są faktycznie stosowane i egzekwowane .
Wszelkie naruszenia powinny być zgłaszane podczas sprawdzania kodu, a przegląd kodu nie powinien być w porządku, jeśli naruszenie jest nierozwiązane:
Oczywiście zmiana reguły oznacza „pójście naprzód” od liderów.
Podoba mi się format w Wytycznych dotyczących projektowania ram, który zawiera ogólną sekcję i uzasadnienia dla wytycznych. Najbardziej użyteczne są szczegóły zaczynające się od Do, Do Not, Unikaj i Rozważ.
Oto przykład w sekcji Implementowanie członków interfejsu. Jawnie zawiera następujące elementy (uwaga, że dla uprzejmości upuściłem uzasadnienie)
Unikaj jawnego wdrażania elementów interfejsu bez wyraźnego powodu
Rozważ wyraźne wdrożenie elementów interfejsu, jeśli elementy mają być wywoływane tylko przez interfejs.
Nie używaj jawnych członków jako granicy bezpieczeństwa.
Podaj chroniony element wirtualny, który oferuje tę samą funkcjonalność, co element jawnie zaimplementowany, jeśli funkcja ma być wyspecjalizowana przez klasy pochodne.
To tworzy dobry ogólny ton. Korzystając z opcji Unikaj i rozważ, możesz pozwolić programistom na wykorzystanie ich oceny. Także dlatego, że są to wytyczne, a nie reguły, które programiści mogą uznać za bardziej smaczne, a tym samym bardziej prawdopodobne, że będą ich przestrzegać.
Wydaje się, że nikt nie wspominał o bezpieczeństwie - w standardzie kodowania musisz mieć odniesienie do wymagań bezpiecznego kodu (np. Użycie modułów sprawdzania poprawności danych wejściowych, niedozwolenie znanych słabych funkcji, takich jak strcpy, wymagania dotyczące obsługi błędów itp.)
Przykłady Starannie ułożone, nietrywialne przykłady zbliżone do świata rzeczywistego, które wykorzystują każdą regułę. Komentarze (niekoniecznie część kodu), która część przykładu podąża za jaką regułą.
Szablony Nie jest to C ++, ale coś do skopiowania-wklejenia i wypełnienia na żywo. O wiele łatwiej jest uzyskać ten 24-liniowy komentarz na płycie, gdy masz odniesienie do kopiowania.
Najważniejsza funkcja: maksymalnie dwie strony.
Jest to coś, co każdy programista powinien przeczytać i zapamiętać. Nie powinieneś szukać standardu za każdym razem, gdy musisz napisać nową funkcję (lub, co gorsza, nową linię). Tak więc, zwięźle i przestrzegaj tylko tych zasad, które naprawdę zwiększają wartość produktu końcowego.
Standardy kodowania to tak naprawdę kilka elementów:
Konwencje kodowania
Najlepsze praktyki
na przykład Nigdy nie zostawiaj pustego połowu po próbie
try { Foo(); } catch { //do nothing }
1) Jeśli istnieje wyjątek zgłoszony przez Foo (), może to powodować inne problemy z następującymi funkcjami, które zakładają, że foo się powiodło.
2) Globalny moduł obsługi błędów nie powiadomi zespołu wsparcia o wyjątku, gdy zdarzy się to na prod
Środowisko kodowania
Standardy kodowania zapisane na papierze są tylko tak skuteczne. Podoba mi się to, jak Go publikuje swój standard kodowania. Ma narzędzie gofmtdo formatowania tekstu programu do formatu. Każda debata na temat formatu kodowania będzie po prostu skutkiem łatki do źródeł gofmt.
Co do tego, jaki format powinien mieć,
if, treść funkcji, bloki instrukcji do jakichkolwiek innych celów,Kiedy czytam kod innych (głównie język C), jeśli nazwy zmiennych / funkcji nie są intuicyjne w kontekście projektu lub jeśli przekraczają pięć poziomów wcięcia lub funkcje wymagają więcej niż sześciu lub siedmiu argumentów lub funkcja działa ponad dwie lub trzy strony na ekranie, bardzo trudno jest odczytać i zrozumieć kod. Zapytany o ulepszenia / prace konserwacyjne, tylko zwiększa trudność. To sprawia, że żałuję, gofmtże program nie powinien być napisany dla każdego projektu (a nawet języka) i każdy plik kodu źródłowego powinien być uruchomiony przez ten program, zanim zostanie on zatwierdzony w projekcie.
Lubię Google JavaScript Style Guide .
Jest zwięzły w swoich wytycznych, ale zawiera szczegółowe informacje, jeśli ich potrzebujesz.