Z niektórych projektów typu open source zebrałem następujący styl kodowania
void someFunction(bool forget);
void ourFunction() {
someFunction(false /* forget */);
}
Zawsze mam wątpliwości, co false
tu oznacza. Czy oznacza to „zapomnieć”, czy też „zapomnieć” odnosi się do odpowiedniego parametru (jak w powyższym przypadku), a „fałsz” ma go zanegować?
Jaki styl jest używany najczęściej i jaki jest najlepszy sposób (lub kilka lepszych sposobów), aby uniknąć dwuznaczności?
coding-style
comments
boolean
Johannes Schaub - litb
źródło
źródło
someFunction(forget: true);
true
sięfalse
i nie zaktualizować komentarz. Jeśli nie możesz zmienić interfejsu API, najlepszym sposobem na skomentowanie tego jestsomeFunction( false /* true=forget, false=remember */)
sortAscending
isortDescending
, lub podobne). Teraz wewnątrz mogą obaj wywołać tę samą metodę prywatną, która może mieć tego rodzaju parametr. Właściwie, jeśli język to obsługuje, prawdopodobnie przekazałbym funkcję lambda, która zawierała kierunek sortowania ...Odpowiedzi:
W opublikowanym przez Ciebie przykładowym kodzie wygląda to jak
forget
argument flagi. (Nie mogę być pewien, ponieważ funkcja jest czysto hipotetyczna).Argumenty flagi są zapachem kodu. Wskazują, że funkcja wykonuje więcej niż jedną rzecz, a dobra funkcja powinna robić tylko jedną rzecz.
Aby uniknąć argumentu flagi, podziel funkcję na dwie funkcje, które wyjaśniają różnicę w nazwie funkcji.
Zgłoś argument
Brak argumentu flagi
edycja: Idealnie, nie musisz wcale obchodzić funkcji z parametrem flag. Są przypadki podobne do tego, co Fowler nazywa splątaną implementacją, w której całkowite oddzielenie funkcji tworzy zduplikowany kod. Jednak im wyższa cykliczna złożoność sparametryzowanej funkcji, tym silniejszy jest argument za jej pozbyciem się.
To tylko przeczucie, ale parametr o nazwie
forget
brzmi jak zazdrość o funkcję. Dlaczego dzwoniący miałby mówić innemu obiektowi, aby o czymś zapomniał? Może występować większy problem projektowy.źródło
serveTraditionalIceCream
iserveLowFatIceCream
jak wyglądają? Mam enum z 14 rodzajami lodów.Słowami laika:
false
jest dosłowne.false
someFunction
żeby nie zapomniećsomeFunction
że parametr zapomnij tofalse
someFunction
pamiętaćMoim zdaniem byłoby lepiej, gdyby funkcja była taka:
możesz to nazwać
lub zachowaj starą nazwę, ale zmień funkcję opakowania na
EDYTOWAĆ:
Jak stwierdził @Vorac, zawsze staraj się używać pozytywnych słów. Podwójna negacja jest myląca.
źródło
remember
, chyba że nazwa funkcji wykonane sensremember
bardzo oczywiste.rememberToCleanUp* or *persist
lub coś.Parametr może być dobrze nazwany; trudno powiedzieć, nie znając nazwy funkcji. Zakładam, że komentarz został napisany przez oryginalnego autora funkcji, i to było przypomnienie o co przechodząc
false
dosomeFunction
środka, ale dla każdego, kto idzie potem, że to trochę niejasne na pierwszy rzut oka.Użycie dodatniej nazwy zmiennej (sugerowanej w Code Complete ) może być najprostszą zmianą, która ułatwiłaby odczytanie tego fragmentu, np.
następnie
ourFunction
staje się:Jednak użycie wyliczenia sprawia, że wywołanie funkcji jest jeszcze łatwiejsze do zrozumienia, kosztem niektórych kodów pomocniczych:
Jeśli nie możesz zmienić podpisu z
someFunction
jakiegokolwiek powodu, użycie zmiennej tymczasowej ułatwia również odczytanie kodu, coś w rodzaju uproszczenia warunków warunkowych poprzez wprowadzenie zmiennej bez żadnego innego powodu niż ułatwienie parsowania kodu przez ludzi .źródło
remember
true oznacza zapomnienie (w twoim przykładziesomeFunction(true /* forget */);
)?enum
zdecydowanie najlepsze rozwiązanie. Tylko dlatego, że typ może być reprezentowany jako -bool
tj. Są izomorficzne - nie oznacza to, że powinien być reprezentowany jako taki. Ten sam argument dotyczy,string
a nawetint
.Zmień nazwę zmiennej, aby wartość bool miała sens.
To milion razy lepsze niż dodawanie komentarza w celu wyjaśnienia argumentów funkcji, ponieważ nazwa jest niejednoznaczna.
źródło
Utwórz lokalny boolean o bardziej opisowej nazwie i przypisz mu wartość. W ten sposób znaczenie będzie bardziej wyraźne.
Jeśli nie możesz zmienić nazwy zmiennej, komentarz powinien być nieco bardziej wyrazisty:
źródło
/* forget */
jest komentarz, który polega na tym, że bez deklaracji funkcji tuż przed tobą może być trudno zapamiętać, co jest ustawionefalse
. (Dlatego uważam, że rada @ Esailii dotycząca dodania wyliczenia jest lepsza i dlatego uwielbiam języki, które pozwalają na nazwane parametry.)Jest dobry artykuł, który wspomina o tej dokładnej sytuacji, ponieważ odnosi się do interfejsów API w stylu Qt. Tam nazywa się to Boolean Parameter Trap i warto ją przeczytać.
Jego istotą jest:
źródło
To dziwny komentarz.
Z punktu widzenia kompilatora
someFunction(false /* forget */);
jest faktyczniesomeFunction(false);
(komentarz jest usuwany). Zatem wszystko, co robi linia, to wywołaniesomeFunction
z pierwszym (i jedynym) argumentem ustawionym nafalse
./* forget */
to tylko nazwa parametru. Prawdopodobnie jest to nic innego jak szybkie (i brudne) przypomnienie, które tak naprawdę nie musi tam być. Wystarczy użyć mniej dwuznacznej nazwy parametru, a komentarz w ogóle nie będzie potrzebny.źródło
Jedną z rad Czystego kodu jest zminimalizowanie liczby niepotrzebnych komentarzy 1 (ponieważ mają one tendencję do gnicia) oraz prawidłowe nazwanie funkcji i metod.
Następnie usunę komentarz. W końcu nowoczesne środowiska IDE (takie jak zaćmienie) wyskakują z kodem po najechaniu myszką na funkcję. Widzenie kodu powinno usunąć niejasności.
1 Komentowanie złożonego kodu jest w porządku.
źródło
Aby pochwalić to, co oczywiste, komentarze mogą kłamać. Dlatego zawsze lepiej jest samokontrować kod bez uciekania się do komentarzy w celu wyjaśnienia, ponieważ pewna osoba (być może ty) zmieni się
true
nafalse
i nie zaktualizować komentarz.Jeśli nie możesz zmienić interfejsu API, skorzystaj z 2 opcji
źródło
Podoba mi się odpowiedź na temat tego, aby komentarz zawsze był prawdziwy , ale choć dobrze myślę, że pomija podstawowy problem z tym kodem - nazywa się go dosłownie.
Powinieneś unikać używania literałów podczas wywoływania metod. Zmienne lokalne, parametry opcjonalne, parametry nazwane, wyliczenia - to, jak najlepiej ich uniknąć, będzie zależeć od języka i dostępnych opcji, ale staraj się ich unikać. Literały mają wartości, ale nie mają znaczenia.
źródło
W C # użyłem nazwanych parametrów, aby to wyjaśnić
Lub
enum
:Lub przeciążenia:
Lub polimorfizm`:
źródło
Nazewnictwo powinno zawsze eliminować dwuznaczność dla boolean. Zawsze nazywam boolean coś takiego jak „isThis” lub „shouldDoThat”, na przykład:
i tak dalej. Ale gdy odwołujesz się do kodu innej osoby, najlepiej pozostaw komentarz podczas przekazywania wartości.
źródło