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