Stało się to wielką frustracją z bazą kodu, nad którą obecnie pracuję; wiele z naszych zmiennych jest krótkich i nieopisowych. Jestem jedynym programistą, który pozostał w projekcie i nie ma dokumentacji dotyczącej tego, co większość z nich robi, więc muszę poświęcić dodatkowy czas na śledzenie tego, co reprezentują.
Na przykład czytałem kod, który aktualizuje definicję powierzchni optycznej. Zmienne ustawione na początku były następujące:
double dR, dCV, dK, dDin, dDout, dRin, dRout
dR = Convert.ToDouble(_tblAsphere.Rows[0].ItemArray.GetValue(1));
dCV = convert.ToDouble(_tblAsphere.Rows[1].ItemArray.GetValue(1));
... and so on
Może to tylko ja, ale w zasadzie nic nie powiedziałem o tym, co reprezentowali, co utrudniło zrozumienie kodu. Wiedziałem tylko, że gdzieś była to zmienna parsująca określony wiersz z określonej tabeli. Po kilku poszukiwaniach dowiedziałem się, co mieli na myśli:
dR = radius
dCV = curvature
dK = conic constant
dDin = inner aperture
dDout = outer aperture
dRin = inner radius
dRout = outer radius
Zmieniłem ich nazwy na to, co tam mam. Wydłuża niektóre linie, ale wydaje mi się, że to sprawiedliwy kompromis. Tego rodzaju schemat nazewnictwa jest jednak używany w wielu częściach kodu. Nie jestem pewien, czy to artefakt od programistów, którzy nauczyli się, pracując ze starszymi systemami, czy może kryje się za tym głębszy powód. Czy istnieje dobry powód, aby nazwać zmienne w ten sposób, czy też mam uzasadnienie, aby zaktualizować je do bardziej opisowych nazw, gdy je napotykam?
źródło
dK = conic constant
.Odpowiedzi:
Wygląda na to, że te nazwy zmiennych oparte są na skrótach, których można się spodziewać w podręczniku do fizyki pracującym nad różnymi problemami optycznymi. Jest to jedna z sytuacji, w której krótkie nazwy zmiennych są często lepsze niż dłuższe nazwy zmiennych. Jeśli masz fizyków (lub ludzi, którzy są przyzwyczajeni do ręcznego opracowywania równań), którzy są przyzwyczajeni do używania typowych skrótów, takich jak Rin, Rout itp., Kod będzie znacznie wyraźniejszy przy tych skrótach niż przy dłuższych nazwach zmiennych. Ułatwia także porównywanie formuł z artykułów i podręczników z kodem, aby upewnić się, że kod właściwie wykonuje obliczenia poprawnie.
Każdy, kto zna się na optyce, natychmiast rozpozna coś w rodzaju Rin jako promień wewnętrzny (na papierze fizyki,
in
będzie renderowany jako indeks dolny), Rout jako promień zewnętrzny itp. Chociaż prawie na pewno byłby w stanie coś mentalnie przetłumaczyć jakinnerRadius
w bardziej znanej nomenklaturze, dzięki temu kod byłby mniej czytelny dla tej osoby. Utrudniłoby to dostrzeżenie przypadków, w których znana formuła została niepoprawnie zakodowana, a także trudniej byłoby przetłumaczyć równania w kodzie na i z równań, które znaleźliby w pracy lub podręczniku.Jeśli jesteś jedyną osobą, która kiedykolwiek ogląda ten kod, nigdy nie musisz tłumaczyć między kodem a standardowym równaniem optyki, i jest mało prawdopodobne, że fizyk kiedykolwiek będzie musiał spojrzeć na kod w przyszłości, być może robi to warto zrefaktoryzować, ponieważ korzyści wynikające ze skrótów nie przewyższają już kosztów. Gdyby to był nowy rozwój, prawie na pewno rozsądne byłoby użycie tych samych skrótów w kodzie, które można znaleźć w literaturze.
źródło
column
w wojskowej grze strategicznej najprawdopodobniej oznacza coś innego niż w oprogramowaniu do tworzenia wykresów.Zmienne o krótkim okresie istnienia powinny zostać wkrótce nazwane. Jako przykład nie piszesz
for(int arrayCounter = 0; arrayCounter < 10; arrayCounter++) { ...
. Zamiast tego używaszfor(int i ...
.Zasadniczo można powiedzieć, że im krótszy zakres zmiennej, tym krótsza powinna być nazwa. Liczniki pętli są często jedynie pojedyncze litery, powiedzmy
i
,j
ik
. Zmienne lokalne są cośbase
Orfrom
ito
. Na przykład zmienne globalne są nieco bardziej rozbudowaneEntityTablePointer
.Być może taka zasada nie jest przestrzegana w bazie danych, z którą pracujesz. Jest to jednak dobry powód, aby dokonać refaktoryzacji!
źródło
i
,j
,k
, piszę coś takiegopersonPos
, bo wtedy nie zapomnę co mi powtarzanie i co indeks reprezentuje.arrayCounter
. Sprawia, że kod jest łatwiejszy do odczytania, a przynajmniej chroni cię przed tupaniem po zewnętrznym liczniku, gdy kopiujesz / wklejasz kolejną pętlę wewnątrz tego.arrayCounter
, bym użyćpersonIndex
lubrow
czy cokolwiek opisane co patrzę.i
. Ale gdy tylko przejdę do zagnieżdżonej pętli, upuszczami
nomenklaturę. Powodem tego jest to, że naprawdę chcę śledzić, która zmienna pętli jest przetwarzana, ai
vsj
może być dość mylące w gęstym kodzie. Uczynienie go bardziej czytelnym i dodanie większej ilości białych znaków jest z natury rzeczy konieczne.Problemem w kodzie nie są krótkie nazwy, ale raczej brak komentarza, który wyjaśniłby skróty lub wskazał kilka pomocnych materiałów na temat wzorów, z których pochodzą zmienne.
Kod po prostu zakłada znajomość domeny problemowej.
To dobrze, ponieważ znajomość problematyczna jest prawdopodobnie wymagana do zrozumienia i utrzymania kodu, szczególnie w roli osoby, która go „posiada”, więc to Ty musisz przyswoić sobie znajomość, a nie obchodzić przedłużające się nazwy.
Byłoby jednak miło, gdyby kod zawierał pewne wskazówki, które mogłyby służyć jako trampoliny. Nawet ekspert w dziedzinie może zapomnieć, że
dK
to stała stożkowa. Dodanie małego „ściągawki” w bloku komentarza nie zaszkodzi.źródło
W przypadku niektórych zmiennych, które są dobrze znane w dziedzinie problemowej - tak jak w tym przypadku - krótkie nazwy zmiennych są rozsądne. Jeśli pracuję nad grą, chcę, aby moje elementy gry miały zmienne pozycji,
x
ay
niehorizontalPosition
iverticalPosition
. Podobnie liczniki pętli, które nie mają żadnych semantykę poza indeksowania, spodziewam się, aby zobaczyći
,j
,k
.źródło
x
iy
, podczas gdy powszechne, nie posiadają ukrytych ważnych aspektów, takich jak gdzie pochodzenie w.for (x,y) in list_of_coordinates: print x,y
: Pochodzenie nie ma szczególnego znaczenia przy próbie zrozumienia kodu.Zgodnie z „Clean Code”:
Nazwy zmiennych powinny:
Wyjątek stanowią przysłowia
i,j,k,m,n
używane w pętlach.Zmienna nazywa cię, na co słusznie narzekasz, nie rób nic z powyższych. Te imiona to złe imiona.
Ponieważ każda metoda musi być krótka , używanie prefiksów wskazujących, że zakres lub typ nie jest już używany.
Te imiona są lepsze:
Komentator mówi, że byłoby to zbyt skomplikowane w przypadku długich nazw zmiennych:
Krótkie nazwy zmiennych również nie ułatwiają:
Odpowiedź to długie nazwy i wyniki pośrednie, dopóki nie otrzymasz tego na końcu:
źródło
fnZR = (r^2/fnR(1+Math.sqrt((1+k)) * (r^2/R^2))) + a[1]*r^2 + a[1]*r^4 + a[1]*r^6 ...;
long_name
R
Istnieją dwa powody, dla których nie należy zmieniać nazw zmiennych w starszym kodzie.
(1) chyba że korzystasz z automatycznego narzędzia do refaktoryzacji, możliwość wprowadzenia błędów jest wysoka. Dlatego „jeśli nie jest zepsuty, nie naprawiaj go”
(2) sprawisz, że porównywanie bieżących wersji z poprzednimi wersjami, aby zobaczyć, co się zmieniło, niemożliwe. Utrudni to w przyszłości utrzymanie kodu.
źródło
Powodem używania mniejszych nazw jest to, że oryginalny programista uważa, że łatwiej z nimi pracować. Przypuszczalnie mają oni prawo do stwierdzenia, że tak jest, i prawo do nie posiadania tych samych osobistych preferencji, co ty. Osobiście znajdę ...
... gdybym używał ich w długich, skomplikowanych obliczeniach. Im mniejsze wyrażenie matematyczne, tym częściej łatwiej jest zobaczyć całość na raz. Chociaż gdyby tak było, mogą być lepsze niż dIn i dOut, więc nie było powtarzającego się D, który mógłby prowadzić do łatwej literówki.
Z drugiej strony, jeśli trudniej ci będzie pracować, powal się i zmień nazwę na dłuższą. Zwłaszcza jeśli jesteś odpowiedzialny za ten kod.
źródło
d
jest Węgier? Myślałem, że to rachunek różniczkowy jak wdx^2/dx = 2x
.dDinnerAperture
, przeczytałbym to jako „Przysłona obiadowa” i zastanawiałem się, czy to tylko zabawny sposób powiedzenia „twoje usta”. Nigdy nie był fanem stylu „wielka litera, po której następuje małe litery”. Czasami bardzo mylące.Generalnie uważam, że regułą tego powinno być stosowanie wyjątkowo krótkich nazw zmiennych, gdy wiesz, że ludzie, którzy są „specjalistami w dziedzinie” twojego konkretnego kodu, natychmiast zrozumieją odniesienie do tej nazwy zmiennej. (W każdym razie zawsze masz komentarze z wyjątkiem tego przypadku) i że zlokalizowane użycie zmiennych można łatwo rozpoznać na podstawie kontekstu ich użycia.
Aby to rozwinąć, oznacza to, że nie powinieneś starać się zaciemniać nazw zmiennych, ale możesz używać skrótów w nazwach zmiennych, ponieważ wiesz, że prawdopodobne jest, że tylko ludzie, którzy rozumieją podstawową koncepcję kodu i tak to przeczytać.
Aby użyć przykładu ze świata rzeczywistego, ostatnio stworzyłem klasę Javascript, która zajmowałaby pewną szerokość geograficzną i mówiła o ilości światła słonecznego, jakiej można oczekiwać w danym dniu.
Aby stworzyć tę klasę Sundial , wspomniałem może o pół tuzina zasobów, Almanachu Astronomii i fragmentach z innych języków (PHP, Java, C itp.).
W prawie wszystkich zastosowali podobne identyczne skróty, co na pierwszy rzut oka nic nie znaczy.
K
,T
,EPS
,deltaPsi
,eot
,LM
,RA
Jeśli jednak posiadasz wiedzę z zakresu fizyki, możesz zrozumieć, czym one były. Nie spodziewałbym się, że ktoś dotknie tego kodu, więc po co używać pełnych nazw zmiennych?
julianTime
,nutationOfEclipticalLongitudeExpressedInDegrees
,equationOfTime
,longitudeMean
,rightAscension
.Ponadto przez większość czasu, gdy nazwy zmiennych są przejściowe, to znaczy, są one używane tylko do tymczasowego przydzielenia pewnej wartości, wtedy często nie ma sensu używać pełnej wersji, szczególnie gdy kontekst zmiennej wyjaśnia, że jest to cel.
źródło
Jest absolutnie; często wystarczy krótka nazwa zmiennej.
W moim przypadku prowadzę nawigację po punktach orientacyjnych w mojej starszej klasie robotyki i programujemy nasze roboty w KISS-C. Potrzebujemy zmiennych dla aktualnych i docelowych (x, y) współrzędnych, (x, y) odległości, bieżących i docelowych pozycji, a także kątów skrętu.
Szczególnie w przypadku współrzędnych xiy długa nazwa zmiennej jest całkowicie niepotrzebna, a nazwy takie jak xC (bieżący x), yD (docelowy y) i pD (docelowy phi) są wystarczające i są najłatwiejsze do zrozumienia w tym przypadku.
Możesz argumentować, że nie są to „opisowe nazwy zmiennych”, jak nakazałby protokół programisty, ale ponieważ nazwy oparte są na prostym kodzie (d = miejsce docelowe, c = bieżące), bardzo prosty komentarz na początku jest całym opisem oni wymagają.
źródło
Zwykle złożone algorytmy są implementowane w matlabie (lub podobnym języku). To, co widziałem, to ludzie po prostu przejmujący nazwę zmiennych. W ten sposób można łatwo porównać implementacje.
Wszystkie pozostałe odpowiedzi są prawie poprawne. Skróty te można znaleźć w matematyce i fizyce, z tym że nie zaczynają się
d
(jak w twoim przykładzie). Zmienne zaczynające się na d są zwykle nazywane w celu reprezentowania różnicowania .Wszystkie normalne przewodniki kodowania mówią, aby nie nazywać zmiennych pierwszą literą reprezentującą typ (jak w twoim przypadku), ponieważ tak łatwo jest przeglądać kod we wszystkich nowoczesnych IDE.
źródło
Mogę wymyślić, dlaczego nazwy zmiennych są dość krótkie.
Krótkie nazwy są łatwe do odczytania dzięki krótszemu zasięgowi oczu, stąd krótki okres uwagi.
Na przykład po przyzwyczajeniu się do faktu, że svdb oznacza „zapisz w bazie danych”, szybkość skanowania kodu źródłowego staje się lepsza, ponieważ muszę tylko szybko skanować 4 znaki zamiast czytać SaveToDatabase (14 znaków, sytuacja się pogarsza dla bardziej złożonych nazw operacji). Mówię „skanowanie”, a nie „czytanie”, ponieważ zajmuje to większą część analizy kodu źródłowego.
Podczas skanowania dużej ilości kodu źródłowego może to zapewnić dobry wzrost wydajności.
Pomaga też leniwemu programistowi wpisywać te krótkie nazwy podczas pisania kodu.
Oczywiście, wszystkie te „skróty” powinny być wymienione w jakiejś standardowej lokalizacji w kodzie źródłowym.
źródło
Aby sformułować to, co @zxcdw powiedział nieco inaczej, i rozwinąć je pod względem podejścia:
Funkcje powinny być czyste , zwięzłe i idealnie obejmować niektóre funkcje: logika czarnej skrzynki , niezależnie od tego, czy siedziała nietknięta od 40 lat, nadal będzie wykonywać zadanie, do którego została zaprojektowana, ponieważ jej interfejs ( wejście i wyjście) brzmi dobrze, nawet jeśli nic nie wiadomo o jego wnętrznościach.
Jest to rodzaj kodu, który chcesz napisać: jest to kod, który trwa i jest łatwy do przeniesienia.
W razie potrzeby komponuj funkcje z innych wywołań funkcji (wstawianych) , aby zachować dokładność kodu.
Teraz, dzięki odpowiednio opisowej nazwie funkcji (w razie potrzeby szczegółowej!), Minimalizujemy ryzyko błędnej interpretacji skróconych nazw zmiennych, ponieważ zakres jest tak mały.
źródło
Nazwy zmiennych powinny być jak najbardziej opisowe, aby zwiększyć czytelność programu. Sam tego doświadczyłeś: miałeś dużo problemów z identyfikacją tego, co zrobił program z powodu złego nazewnictwa.
Nie ma dobrego powodu, aby nie używać nazwy opisowej. Pomoże ci i wszystkim innym, którzy pracują / będą pracować nad projektem. Cóż, w rzeczywistości istnieje jedno prawidłowe użycie krótkich nazw: liczniki pętli.
źródło
int dummy_variable_for_for_loops;
jest jak najbardziej opisowy.Na pewno po to są // komentarze?
Jeśli zadania mają opisowe komentarze, otrzymujesz to, co najlepsze z obu światów: opis zmiennej i wszelkie równania są łatwo porównywalne z ich odpowiednikiem z podręcznika.
źródło
W przypadku interfejsów (np. Podpisów metod, podpisów funkcji) staram się to rozwiązywać, opisując deklaracje parametrów. W przypadku C / C ++ dekoruje on plik .h, a także kod implementacji.
Robię to samo dla deklaracji zmiennych, gdzie znajomość użycia zmiennej nie jest oczywista w kontekście i nazewnictwie. (Dotyczy to także języków, które nie mają silnego pisania).
Jest wiele rzeczy, których nie chcemy zatkać nazwy zmiennej. Czy kąt w radianach lub stopniach, czy istnieje pewna tolerancja dla precyzji lub zasięgu itp. Informacje te mogą dostarczyć cennych twierdzeń na temat cech, z którymi należy odpowiednio sobie radzić.
Nie jestem z tego powodu religijny. Interesuje mnie po prostu przejrzystość i upewnienie się, że teraz jestem tym, co następnym razem moje zapomniane ja odwiedzi kod. A każdy, kto patrzy przez ramię, ma to, co musi wiedzieć, aby zobaczyć, gdzie coś jest nie tak, co jest niezbędne (ostatnie ważne dla właściwej konserwacji).
źródło
Po pierwsze: Nazywanie zmiennej dla energii e podczas obliczania wzorów takich jak E = MC2 NIE jest nazbyt krótkim nazewnictwem. Użycie symboli jako argumentu dla krótkich nazw jest nieprawidłowe
To pytanie było dla mnie dość interesujące i mogę wymyślić tylko jedną wymówkę, a mianowicie pieniądze.
Załóżmy na przykład, że instalujesz javascript dla klienta, który wie, że plik ma zostać pobrany wiele razy na sekundę. Byłoby to tańsze i poprawiłoby wrażenia użytkowników, gdyby plik (w liczbie bajtów) był jak najmniejszy.
(Aby zachować przykład „realistyczności”, nie wolno ci używać narzędzia minifikatora, dlaczego? Problemy bezpieczeństwa, żadne zewnętrzne narzędzia nie mogą dotykać podstawy kodu).
źródło
Zauważam, że inne odpowiedzi nie wspominają o użyciu notacji węgierskiej. Jest to ortogonalne dla debaty długościowej, ale ogólnie dotyczy schematów nazewnictwa.
Litera „d” na początku wszystkich tych zmiennych ma oznaczać, że są one podwójne; ale język i tak to wymusza. Pomimo zwięzłości tych nazw, są nawet o 50% zbędne !
Jeśli zamierzamy zastosować konwencję nazewnictwa w celu zmniejszenia liczby błędów, znacznie lepiej kodujemy informacje, które nie są sprawdzane przez język. Na przykład żaden język nie będzie narzekał
dK + dR
w powyższym kodzie, nawet jeśli dodawanie liczby bezwymiarowej do długości jest bez znaczenia.Dobrym sposobem zapobiegania takim błędom jest użycie silniejszych typów; jeśli jednak będziemy używać podwójnych, bardziej odpowiednim schematem nazewnictwa może być:
Język nadal pozwoli nam pisać
K + lR
, ale teraz nazwy dają nam podpowiedź, że może to być niepoprawne.Jest to różnica między systemami węgierskimi (ogólnie źle) a aplikacjami węgierskimi (być może dobrym)
http://en.wikipedia.org/wiki/Hungarian_notation
źródło
K + lR
jeśli prawidłowo zadeklarujesz swoje jednostki. Dzięki jednostkom SI może przeprowadzać kontrole wymiarów i konwersję jednostek. Dodawanie nie3_feet + 2_meter
powinno stanowić problemu, a2_meter+1_second
błąd kompilacji.Jedyny przypadek, w którym nieczytelnie krótkie nazwy zmiennych są dopuszczalne w nowoczesnej inżynierii oprogramowania jest, gdy występują one w skrypcie i przepustowość tego skryptu (przez sieć ogólnie) jest bardzo ważne. Nawet wtedy trzymaj skrypt z długimi nazwami pod kontrolą źródła i zminimalizuj skrypt w trakcie produkcji.
źródło
radius
gdy przechowuje wewnętrzny promień, nie rozumiejąc, że jest to o wiele bardziej dwuznaczne niżRin
). Następnie programista niebędący ekspertem musi tłumaczyć między swoją unikalną nomenklaturą a nomenklaturą, którą firma rozumie za każdym razem, gdy pojawia się dyskusja z udziałem równań.