Poprawa czytelności kodu [zamknięty]

• spójny styl formatowania
• dobre wykorzystanie białej przestrzeni
• Używanie krótkich, ale znaczących nazw
• nie za dużo komentarzy (jak wspomniałeś), ale kiedy to zrobię, skomentuj whys kodu, a jeśli ma to zastosowanie, why nots (dlaczego nie użyto innej implementacji, zwłaszcza jeśli wydaje się, że powinno to być oczywiste).
• nie Optymalizuj kodu, dopóki profiler nie powie mi, że jest powolny lub nieefektywny

Używaj dobrych nazw zmiennych i metod. Podziel kod na znaczące części, które osiągają określone cele. Zachowaj spójność klas (wszystko działa razem) i oddzielenie (istnieje kilka zależności między klasami). Nie powtarzaj się (na sucho). Postępuj zgodnie z zasadami Uncle Boba (nie prawami, jak on wskazuje) w stopniu, w jakim działają one na rzecz ulepszenia kodu.

Książka clean code Z "uncle bob" daje całkiem dobry przegląd tego, jak powinny wyglądać funkcje, z praktycznymi przykładami.

Niektóre ważne punkty:

• małe funkcje, klasy
• dobre, znaczące, nazwy, rozmiar nie ma znaczenia, ale powinny być dokładnie tak długie, jak potrzeba
• odstępy pionowe między funkcjami / zmiennymi powinny być niskie (deklarować rzeczy jak najbliżej miejsca, w którym są używane po raz pierwszy)
• funkcje i klasy powinny robić jedną rzecz i tylko jedno

Książka ma o wiele więcej małych zasad, naprawdę polecam. Również uzyskać kod Complete 2.

Kod samokontroli to:

• dobre konwencje nazewnictwa
• przejrzysta konstrukcja i rozdzielenie odpowiedzialności pomiędzy komponenty (Klasa, funkcja itp.)

Pamiętaj jednak, że nawet najbardziej samodokumentujący się kod może udokumentować tylko to, co tam jest; Nigdy to, co zostało celowo pominięte, zoptymalizowane, wypróbowane i odrzucone itp. Zawsze będziesz potrzebował języka angielskiego w swoich plikach źródłowych lub będziesz musiał pominąć ważne zastrzeżenia i projekt decyzje.

Generalnie nie komentuję w kodzie, jednak całkowicie nie zgadzam się z często utrzymywanym poglądem, że należy po prostu napisać czytelny kod, a potem nie trzeba dokumentacji.

To, co myślę powinno być udokumentowane, to twój interfejs . Przez to mam na myśli, że powinny być komentarze powyżej klas i metod. Nie proste metody jak set I get oczywiście.

Osoby korzystające z klas i metod napisanych przez Ciebie nie powinny czytać Twojego kodu, aby zrozumieć jak ich używać. Myślę więc, że należy udokumentować, jakie są prawne zakresy wejścia i wyjścia, a także ważne niezmienniki. Np. funkcja przyjmuje wskaźnik jako argument. Bez względu na to, jak dobrze nazwiesz swoją funkcję, nigdy nie może być oczywiste, czy podanie NULL jest poprawne, czy NULL jest poprawnym zwracanym wynikiem. Często -1 i 0 są używane do sygnalizowania czegoś w rodzaju szukanego obiektu not found lub podobnego. To powinno być udokumentowane.

Poza tym myślę, że kluczem do dokumentowania kod nie jest po to, aby dokumentować, co klasa lub Metoda robi lub jest, ale co intencja za nim jest.

Miej Konwencję kodowania {[2] } między tobą a twoimi kolegami. Zaczynając od wcięcia, obejmując nawiasy, aż do "skąd pochodzi nawias klamrowy: nowa linia, ta sama linia?"

W Visual Studio można wybrać i naprawić ten styl. Pomaga wszystkim innym w czytaniu tego samego kodu. Ułatwia to również śledzenie historii w systemie wersjonowania, gdy nie trzeba rozróżniać "pustych" edycji (zmiana stylu) i rzeczywistych edycji.

Trzymaj się paradygmatu używanego w środowisku, które kodujesz.

Oczywistym przykładem jest użycie przypadku Pascala dla metod w. NET, przypadku wielbłąda w Javie.

Mniej oczywiste przykłady odnoszą się do używania tych samych konwencji, które są używane w standardowej bibliotece klas.

Jest wiele do powiedzenia na ten cel. Konwencje nazewnictwa przekazują wiele informacji dla ludzi, a bardzo niewiele dla kompilatora. Każdy, kto korzystał z API w jednym środowisku, które korzysta z konwencje innego środowiska zauważyły, jak bardzo wyróżnia się obcy kod.

Spójność jest cenną cechą, która zmniejsza obciążenie poznawcze ludzkiego konsumenta kodu.

Eschew codejunk.

Edward Tufte ma piękną, potężną koncepcjęchartjunk , elementów wizualnych na wykresie, które przyczyniają się do szumu, a nie Informacji. Myśląc o wykresach w ten sposób, tworzymy znacznie wyraźniejsze wykresy.

To, co tworzy chartjunk, zależy od zespołu, środowiska i projektu-niektórzy ludzie lubią brodawki; niektóre środowiska renderują kod w sposób, który czyni pewne śmieci użytecznymi( na przykład dopasowanie brace i komentarze // end for); niektóre projekty wymagają bardziej obszernego komentowania, aby dostosować się do standardów lub kompleksowo udokumentować API. Ale kiedy zespół ustali standardy, co oznacza chartjunk dla swoich projektów, wiele decyzji staje się łatwiejszych, a jego kod staje się bardziej spójne i czytelne.

Wszystkie odpowiedzi (i pytanie) opierają się na założeniu, że czytelność jest wyłącznie odpowiedzialnością autora kodu. Jeśli tak naprawdę nie chcesz czytać kodu i masz listę rezygnacji z czytania (zapach kodu), która pasuje do 99% dostępnego kodu i nie chcesz nawet bardzo mocno myśleć o tym, co robi jakiś kod, to nie znajdziesz żadnego czytelnego kodu.

Jakiekolwiek zasady, których używamy dzisiaj, aby uczynić nasz kod bardziej czytelnym, będą wyglądać staro / align = "left" / Jeśli naprawdę chcesz lepszej czytelności kodu, przeczytaj jakiś stary kod (pozwolić na modę czasu, że musiał działać na maszynie z 1000-tą prędkością i pamięcią, którą masz), Postaraj się go zrozumieć i zachęcić kogoś innego do zrobienia tego samego.