Co powinno być w standardzie kodowania? [Zamknięte]

Co powinno być w dobrym (czytaj: przydatnym) standardzie kodowania?

• Rzeczy, które powinien mieć kod.
• Czego kod nie powinien mieć.
• Czy standard kodowania powinien zawierać definicje rzeczy, które wymusza język, kompilator lub formatator kodu?
• Co z danymi takimi jak złożoność cykliczna, liczba wierszy na plik itp.?

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

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ę):

• 80% pokrycia testów jednostkowych
• Zbiorowa własność kodu (napisz kod do odczytania przez kolegów z zespołu, a nie kompilatora)
• Napisz komentarze. Napisz, co powiesz nowicjuszowi.
• Nie komplikuj

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ż

• nazwy jasno opisują, jakie dane są manipulowane,
• szelki sprawiają, że kontrola jest czysta,
• komentarze wyjaśniają każdy nieoczywisty algorytm itp.

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:

• Czy ta reguła pomaga upewnić się, że kod jest poprawny ?
• Czy ta reguła pomaga upewnić się, że kod jest czysty ?

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.

Procedura recenzji kodu w celu egzekwowania standardu. Aha, i żeby znaleźć błędy.

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.

• Aspekt techniczny: który ma na celu unikanie ryzykownego lub źle sformułowanego kodu (nawet jeśli został zaakceptowany przez kompilator / tłumacza)
• Aspekt prezentacji: dotyczy samego przedstawienia programu czytelnikom

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:

• Tytuł, prosty i na temat
• Podsumowanie, które wyjaśnia tytuł
• Dyskusja, która ilustruje problem postępowania w inny sposób, a tym samym przedstawia uzasadnienie
• opcjonalne Niektóre przykłady, ponieważ dobry przykład jest wart tysiąca słów
• opcjonalne Lista wyjątków, dla których nie można zastosować tej reguły, czasem z obejściem
• Lista odnośników (inne książki, strony internetowe), które omawiały ten punkt

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:

• wolą metody krótkie od długich: zazwyczaj trudno jest ustalić, jaka jest długość
• wolą wczesny powrót / kontynuuj / przerwa, aby zmniejszyć wcięcie

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:

• napraw kod, aby pasował do reguły
• napraw regułę, aby kod już się nie wyróżniał

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

• te rzeczy nie potrzebują innego powodu niż „spójność bazy kodu” np. używać „_” w zmiennych prywatnych członków lub nie.
• może istnieć kilka poprawnych podejść. Wystarczy wybrać jeden dla zachowania spójności. na przykład obsługa błędów przy użyciu wyjątków lub kodów błędów.

Najlepsze praktyki

• te elementy zawsze wymagają dobrego uzasadnienia z kilkoma wyraźnymi przykładami

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

• obejmuje praktyki „Defensywnego kodowania”, takie jak używanie Asertów do testowania swoich założeń.

Środowisko kodowania

• narzędzia, z których korzysta cały zespół. na przykład VS 2010, Resharper, piec itp.

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ć,

• jak nazwać zmienne, makra, stałe, literały, funkcje itp
• jak umieszczać {,}, (,), [,], jeśli chodzi o if, treść funkcji, bloki instrukcji do jakichkolwiek innych celów,
• jak szerokie powinny być wcięcia,
• ile znaków dozwolony jest wiersz tekstu
• ile poziomów wcięć jest dozwolonych, zanim kod zostanie odrzucony / wysłany do refaktoryzacji
• ile wierszy kodu jest dozwolonych na funkcję przed wysłaniem jej z powrotem do refaktoryzacji
• maksymalna liczba argumentów, które funkcja może przyjąć, zanim zostanie odesłana do refaktoryzacji
• Kilka linii komentarzy, zanim funkcja zacznie krótko wyjaśniać, co robi, jeśli treść ma przekroczyć jedną stronę kodu ekranowego; pozostawiając sposób osiągnięcia obiektu do kodu w ciele funkcji

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.

Kod samo dokumentujący (komentarze, nazwy zmiennych, nazwy funkcji itp.)