Tworzenie dokumentu standardów kodowania

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?

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.

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.

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,

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).

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.