Tworzenie dokumentu standardów kodowania

15

Pracuję w firmie zajmującej się systemami sterowania, gdzie podstawową pracą są SCADA i PLC , a także inne elementy systemów sterowania.

Tworzenie oprogramowania nie jest tak naprawdę czymś, co robi firma, z wyjątkiem drobiazgów tu i tam, dopóki nie podjęto decyzji o stworzeniu wewnętrznego systemu zarządzania projektami i oceny.

Ten projekt został podjęty przez ludzi, którzy pierwotnie przybyli tutaj jako ludzie oprogramowania i jesteśmy głównie młodsi.

Projekt rozpoczął się od małych, więc dokumentowaliśmy tylko takie rzeczy, jak projekt, bazy danych itp., Ale tak naprawdę nigdy nie uzgodniliśmy formatu / konwencji kodowania.

Zaczęliśmy używać StyleCop, aby mieć pewność, że mamy dobrze udokumentowany kod, ale uważam, że potrzebujemy oficjalnego dokumentu do kodowania konwencji / praktyk, abyśmy mogli kontynuować dobry standard, a jeśli w przyszłości będzie więcej poważnych prac programistycznych, ktokolwiek na nim pracuje. ma dobrą podstawę.

Na tym polega problem, nie mam pojęcia, jak przygotować dokument do kodowania konwencji i standardów, wszystko, co mogę wymyślić, to przykłady dobrych i złych praktyk (na przykład przypadek wielbłąda przy nazywaniu zmiennych, unikanie węgierskiej notacji itp.) Wszyscy jesteśmy wystarczająco kompetentni programiści (najwyraźniej), ale po prostu nie mamy karty do tego rodzaju rzeczy.

Aby na to zwrócić uwagę, moje pytanie brzmi: jakie są kluczowe aspekty i treść dobrego dokumentu standardów kodowania?

Felix Weir
źródło
2
Czy masz już pełny zakres testów? Nie ma znaczenia, jak ładny jest kod, jeśli jest niepoprawny ...
JBRWilkinson
2
Dobrą rzeczą jest to, że gruntownie testujemy nasze produkty, przeprowadziliśmy regularne testy jednostkowe dla naszego projektu, a przed wydaniami będziemy korzystać z losowych testów na korytarzu i napisać specyfikację testu do testowania czarno-białych skrzynek.
Felix Weir
Priorytetem naszej małej grupy jest to, że nasz kod jest solidny i nie można go złamać. Używamy również Bugzilli do śledzenia błędów i niestandardowego narzędzia zgłaszania błędów dla użytkowników.
Felix Weir
Oto niektóre zasoby uważane za „klasyczne” prace na ten temat. Proponuję wziąć najlepsze części tych standardów, aby stworzyć dokument, który spełnia potrzeby twojej grupy: 1. Bell Labs, Indian Hill C Style and Coding Standards, 19 lutego 1997 r., Maultech.com/chrislott/resources/cstyle/indhill-cstyle .pdf 2. Stallman, Richard, GNU Coding Standards, 30 czerwca 2012 r., gnu.org/prep/standards/standards.html 3. Jet Propulsion Laboratory, JPL Institutional Coding Standard for C Programming Language, wersja 1.0, 3 marca 2009 r., lars-lab.jpl.nasa.gov/JPL_Coding_Standard_
William Leara

Odpowiedzi:

24

Jakie są kluczowe aspekty i treść dobrego dokumentu standardów kodowania?

  1. Jest wspierany przez narzędzia, które umożliwiają automatyczną sprawdzania kodu . Jeśli wiem, że nie mogę zobowiązać się do kontroli wersji jakiegokolwiek kodu, który nie pasuje do niektórych reguł, zachęcam do przestrzegania tych zasad w moim kodzie. Z drugiej strony, jeśli jakiś programista napisał gdzieś, że muszę przestrzegać reguły, nie mam bzdur na temat tych reguł.

  2. Być dobrze przemyślanym, a nie osobistą opinią . Nie mówicie wprost: „odtąd nie używamy już regionów, ponieważ nie lubię regionów”. Wyjaśniłbyś raczej, że regiony sprzyjają rozwojowi kodu i nie rozwiązują żadnego poważnego problemu .

    Powodem jest to, że w pierwszym przypadku twój kolega z pracy odpowiedziałby: „no cóż, lubię regiony, więc nadal z nich skorzystam”. Z drugiej strony zmusiłoby to ludzi, którzy nie zgadzają się z konstruktywną krytyką, sugestiami i argumentami, ostatecznie zmuszając cię do zmiany pierwotnej opinii.

  3. Być dobrze udokumentowany . Brak dokumentacji powoduje zamieszanie i pole do interpretacji ; zamieszanie i możliwość interpretacji prowadzą do różnicy stylów, tzn. rzeczy, które standardy chcą tłumić.

  4. Jest szeroko rozpowszechniony, w tym poza firmą . „Standard” używany przez dwudziestu programistów jest mniej standardowy niż standard znany setkom tysięcy programistów na całym świecie.

Ponieważ mówisz o StyleCop, przypuszczam, że aplikacja jest napisana w jednym z języków .NET Framework.

W takim przypadku, chyba że masz poważne powody, by postąpić inaczej, po prostu trzymaj się wytycznych Microsoft. Robienie tego ma kilka zalet, a nie tworzenie własnych standardów. Biorąc cztery poprzednie punkty:

  1. Nie musisz przepisywać reguł StyleCop, aby pasowały do ​​własnych standardów. Nie twierdzę, że trudno jest napisać własne zasady, ale jeśli możesz tego uniknąć, oznacza to, że masz więcej czasu na zrobienie czegoś pożytecznego.

  2. Wytyczne Microsoft są bardzo dobrze przemyślane. Są szanse, że jeśli się nie zgodzisz z niektórymi z nich, może to wynikać z tego, że ich nie rozumiesz. To była dokładnie moja sprawa; kiedy zacząłem programować w C #, znalazłem kilka zasad całkowicie głupich. Teraz całkowicie się z nimi zgadzam, ponieważ w końcu zrozumiałem, dlaczego zostały napisane w ten sposób.

  3. Wytyczne Microsoft są dobrze udokumentowane, więc nie musisz pisać własnej dokumentacji.

  4. Nowi programiści, którzy zostaną później zatrudnieni w Twojej firmie, mogą już znać standardy kodowania Microsof. Istnieją pewne szanse, że nikt nie będzie zaznajomiony z twoim wewnętrznym stylem kodowania.

Arseni Mourzenko
źródło
Mamy kontrolę wersji (SVN, mamy nadzieję, że wkrótce przejdziemy do GIT), a kierownictwo projektu zawsze przypomina nam o regularnej aktualizacji, a następnie o zobowiązaniu się do unikania masowych konfliktów (przynajmniej kilka razy w tygodniu).
Felix Weir
BTW, wspominasz o „narzędziach umożliwiających automatyczne sprawdzanie”, które to są? Jestem ciekaw.
Felix Weir
@FelixWeir: dla .NET Framework? StyleCop.
Arseni Mourzenko
No tak, myślałem, że sugerujesz coś innego. Używamy Stylecop ...: ^)
Felix Weir
1
@FelixWeir: spróbuj także (jeśli jeszcze tego nie zrobiłeś) analiza kodu. Cel jest inny i nie jest związany z samym stylem, ale umożliwia również standaryzację.
Arseni Mourzenko
8

Pierwszą ważną rzeczą, na którą należy zwrócić uwagę, jest to, że dokument standardów kodowania nie dotyczy dobra i zła. Nie chodzi o dobre i złe ani o to, która metoda jest lepsza.

Celem dokumentu standardów kodowania jest upewnienie się, że cały kod jest zaprojektowany, napisany i ułożony tak samo, aby ułatwić programistom przełączanie się z pracy jednej osoby na drugą bez konieczności zmiany mentalności w celu odczytania stylu innej osoby.

Chodzi o jednolitość, a nic o „dobro i zło”

Mając to na uwadze, w dokumencie dotyczącym standardów kodowania należy wyjaśnić:

Konwencje nazewnictwa

Jak nazwiesz swoje metody, zmienne, klasy i interfejsy? Jakiej notacji będziesz używać?

Coś jeszcze zawartego w naszych standardach to oddzielne standardy dla SQL, więc mieliśmy podobne nazwy dla tabel, procedur, kolumn, pól identyfikatora, wyzwalaczy itp.

Wcięcie

Czego użyjesz do wcięcia? Jedna zakładka? 3 spacje?

Układ

Czy nawiasy klamrowe będą utrzymywane na tej samej linii co linia metody otwierania? (ogólnie java) lub w następnym wierszu lub w wierszu własnym? (ogólnie C #)

Obsługa wyjątków / rejestrowanie

Jakie są twoje standardy w zakresie obsługi wyjątków i rejestrowania, czy wszystko jest uprawiane w domu, czy używasz narzędzia innej firmy? Jak należy go używać?

Komentowanie

Mamy standardy dyktowania poprawności gramatycznej, a komentarze zaczynają się na linii przed lub po, a nie na tej samej linii, co zwiększa czytelność. Czy komentarze będą musiały być wcięte na tej samej głębokości co kod? Czy zaakceptujesz ramki komentarzy używane w przypadku większych tekstów?

A co z metodami opisów? Czy należy ich użyć? Gdy?

Ekspozycja

Czy wszystkie twoje metody i pola powinny zapewniać możliwie najniższy poziom dostępu?

Ważna rzecz do zapamiętania. Dokument dotyczący dobrych standardów może pomóc w sprawdzeniu kodu, czy spełnia te minimalne standardy?

Ledwo zarysowałem powierzchnię tego, co może znaleźć się w jednym z tych dokumentów, ale KISS

Nie rób tego długo, nudnego i niemożliwego do przejścia, bo te standardy po prostu nie będą przestrzegane, bądź prosty.

RhysW
źródło
1
Standardów kodowania często, zwłaszcza dla rozwoju C / C ++, a także zawierać (duży) sekcję o których język konstrukty należy nie używać i dlaczego.
Bart van Ingen Schenau
2
@BartvanIngenSchenau nie ma powodu, dla którego potrzebujesz ich do C ++ lub dlaczego nie potrzebujesz podobnych sekcji dla innych języków - możesz zrobić bałagan z C # lub JS lub ... cóż, cokolwiek. Wszystkie języki mają „funkcje, których można niewłaściwie używać”. Najlepiej wytrenuj swoich programistów, aby byli dobrzy w swojej pracy, zamiast wypełniać standardowy dokument mini tutorialami „jak nie kodować”.
gbjbaanb
@gbjbaanb: Nie mogę komentować innych języków, ale C ++ ma wystarczająco dużo ciemnych narożników i pułapek, że nie chodzi o unikanie niewłaściwego użycia, ale raczej odciągnięcie ludzi od funkcji trudnych w użyciu (na przykład przeładowanie &&). Trening jest dobry, ale czasami lepiej mieć dobry dokument referencyjny, aby odświeżyć pamięć, dlaczego nie powinieneś tego robić.
Bart van Ingen Schenau
1
@BartvanIngenSchenau uważam, że lepiej byłoby umieścić go w dokumencie z wytycznymi dotyczącymi kodowania , a nie w dokumencie ze standardami kodowania
RhysW
@RhysW: Wystarczająco uczciwe. Z mojego doświadczenia wynika, że ​​oba są zwykle łączone w jednym dokumencie (zatytułowanym „Standard kodowania”), ale nie widzę problemu w dwóch dokumentach.
Bart van Ingen Schenau
6

Przechodziłem przez ten proces wiele razy. A najbardziej udanym (choć i tak wyboistym) było podejście do wzięcia dokumentu „Standardów kodowania” od znanej firmy i zmodyfikowanie go, aby pasował do twoich potrzeb.

Na przykład właśnie znalazłem ten: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

W każdym razie trzymaj pod ręką miotacza ognia.

Twoje zdrowie,

Miłosz Krajewski
źródło
2
+1 Chciałem powiedzieć to samo. Tworzenie dokumentu standardów kodowania to ogromne zadanie, które zostało już wykonane. Znajdź dobry, a następnie zmień, aby dostosować.
John MacIntyre
4

Nienawidzę większości standardowych dokumentów, ponieważ zwykle próbują pocić małe rzeczy i ignorują większy obraz.

Na przykład prawie wszystkie z nich powiedzą, jak nazwać zmienne lub wstawić nawiasy. Jest to czysty styl i niewiele robi, aby naprawdę pomóc grupie deweloperów poprawnie. Ignorują takie elementy, jak struktura katalogów i układ kodu. Widziałem standardowe dokumenty, które mówiły dokładnie o tym, ile spacji należy wstawić między operatorami i ile pustych linii między metodami. Wszystko to zwykle kończy się mnóstwem wyjątków od reguły, która po prostu pokazuje, jak bardzo są bezcelowi, a potem są tak duże, że nikt nie może ich przestrzegać, co ponownie kpi z punktu, który starają się uczynić .

Teraz używam wielu różnych programów od wielu różnych ludzi i każdy ma inny styl. Po prostu przyzwyczajam się do tego, nie narzekam, że nie ma wspólnego stylu we wszystkich grupach programistycznych. Tak długo, jak kod jest wspólnym stylem w całym projekcie, tak naprawdę nie obchodzi mnie, jaki to styl. Tak więc moją pierwszą zasadą dla wszystkich dokumentów standardowych jest: Zachowaj spójny styl kodowania w projekcie . nikt nie powinien podawać figi w nawiasach, o ile wszystkie są takie same. Weź wojny religijne i wepchnij je :)

Drugi to układ kodu. Kiedy wybieram fragment kodu, chcę zobaczyć, że jest on ułożony w podobny sposób jak inne, podobne fragmenty pracy. Jeśli mam usługę internetową, chcę, aby nazwa umowy wsdl była wyraźna, chcę, aby nazwa implementacji była czysta. Nie chcę, aby ktoś wymyślił zupełnie nowy i inny układ plików i klas. Oznacza to, że muszę grać w „polowanie na kod”, co jest uciążliwe. Jeśli wygląda tak samo jak ostatni projekt, nad którym pracowałem, od razu mogę wiedzieć, gdzie znaleźć to, czego szukam i jest to prawdopodobnie największa pomoc w pracy z kodem innych osób, którą znam. Więc zachować strukturę jak kod jest określone (np folderze Documentation w Dokumentach, interfejsy dla interfejsów itp - cokolwiek to jest, że działa dla Ciebie, ale trzymać się go).

Artefakty kodu również powinny być obecne, więc musisz powiedzieć, czy oczekiwaną obsługą błędów są wyjątki czy kody błędów - tj. dokumentuj funkcjonalność architektoniczną, która jest w użyciu . Powinien również określać, jakiego rodzaju rejestrowania używać i jak prezentować logi / obsługę błędów użytkownikowi lub dowolnemu podsystemowi używanemu do zarządzania kodem w środowisku naturalnym. Pracowałem w miejscu, w którym każdy projekt logował się inaczej - żałosne było to, że każda wersja kodu musiała mieć swój własny, inny dokument operacyjny, informujący facetów operacyjnych, jak stwierdzić, czy coś poszło źle. Dziennik zdarzeń, plik dziennika (w którym to przypadku) itp. Są tutaj ważne. To samo dotyczy innych typowych aspektów kodu - jak go skonfigurować (nie ma sensu używać pliku .config dla niektórych programów, niestandardowej bazy danych, parametrów wiersza poleceń lub rejestru dla innych).

Krótko mówiąc, liczy się tylko spójność . A ponieważ dokumenty o wysokich standardach są zbyt duże, by je czytać i zapamiętywać, wolę po prostu informować ludzi o rzeczach, których nie widzą (np. Standardy architektoniczne, takie jak rejestrowanie) i powiedzieć im, aby zachowali spójność pisanego kodu z tym, co jest obecnie dostępne. A jeśli nie masz jeszcze kodu, nie potrzebujesz dokumentu standardu! (cóż, nie dopóki nie napiszesz wystarczająco dużo, aby było to przydatne).

Więc weźmy od tego główne punkty: nie próbuj tworzyć legalnego dokumentu , pomyśl o rzeczach, które nie są tylko kodowaniem, ale także o tym, jak działa kod i jak kod pasuje do oczekiwań innych ludzi. Następnie ufaj ludziom, że robią dobry kod, a zobaczysz, że robią. (a jeśli nie, możesz mieć ze sobą słowa, nie musisz kłaść tego jak prawo).

gbjbaanb
źródło
2

Nie, to całkowita strata czasu i energii. StyleCop jest świetny i został założony przez lata przez ludzi o wiele bardziej doświadczonych i mądrzejszych niż ty lub ktokolwiek z twojego zespołu. Obejmuj i kochaj to! Prowadzi Cię w sposób ciągły, co jest lepsze niż jakikolwiek dokument czekający na kogoś, kto może mieć problem z jego odczytaniem.

Martin Maat
źródło