Komentar yang benar untuk menempatkan argumen fungsi boolean yang "salah"?

Dari beberapa proyek open source, saya mengumpulkan gaya pengkodean berikut

void someFunction(bool forget);

void ourFunction() {
  someFunction(false /* forget */);
}    

Saya selalu ragu tentang apa falseartinya di sini. Apakah ini berarti "lupa", atau "lupa" merujuk pada parameter yang sesuai (seperti dalam kasus di atas), dan "salah" dimaksudkan untuk meniadakannya?

Gaya apa yang paling sering digunakan dan apa cara terbaik (atau beberapa cara yang lebih baik) untuk menghindari ambiguitas?

Dalam kode sampel yang Anda poskan, sepertinya forgetargumen flag. (Saya tidak bisa memastikan karena fungsinya murni hipotetis.)

Argumen bendera adalah bau kode. Mereka menunjukkan bahwa suatu fungsi melakukan lebih dari satu hal, dan fungsi yang baik seharusnya hanya melakukan satu hal.

Untuk menghindari argumen flag, pisahkan fungsi menjadi dua fungsi yang menjelaskan perbedaan dalam nama fungsi.

Bendera argumen

serveIceCream(bool lowFat)

Tidak ada argumen bendera

serveTraditionalIceCream()
serveLowFatIceCream()

sunting: Idealnya, Anda tidak perlu tetap menggunakan fungsi dengan parameter flag sama sekali. Ada kasus-kasus di sepanjang garis dari apa yang Fowler sebut implementasi kusut di mana sepenuhnya memisahkan fungsi-fungsi menciptakan kode duplikat. Namun, semakin tinggi kompleksitas siklomatik dari fungsi parameter, semakin kuat argumen untuk menghilangkannya.

Dalam kata-kata awam:

• false adalah literal.
• Anda lulus secara literal false
• Anda mengatakan someFunctionuntuk tidak melupakan
• Anda mengatakan someFunctionbahwa parameter lupa adalahfalse
• Anda mengatakan someFunctionuntuk mengingat

Menurut pendapat saya akan lebih baik jika fungsinya seperti ini:

void someFunction(bool remember);

Anda bisa menyebutnya

void ourFunction() {
  someFunction(true);
} 

atau simpan nama lama tetapi ubah fungsi wrapper Anda menjadi

void ourFunctionWithRemember() {
  someFunction(false);
} 

EDIT:

Seperti yang dikatakan @Vorac, selalu berusaha untuk menggunakan kata-kata positif. Negasi ganda membingungkan.

Parameter mungkin bernama baik; sulit untuk mengatakannya tanpa mengetahui nama fungsinya. Saya berasumsi bahwa komentar itu ditulis oleh penulis asli dari fungsi, dan itu adalah pengingat dari apa yang lewat falseke dalam someFunctionberarti, tetapi bagi siapa saja yang datang bersama sesudahnya, itu sedikit tidak jelas pada pandangan pertama.

Menggunakan nama variabel positif (disarankan dalam Kode Selesai ) mungkin merupakan perubahan paling sederhana yang akan membuat potongan ini lebih mudah dibaca, misalnya

void someFunction(boolean remember);

kemudian ourFunctionmenjadi:

void ourFunction() {
    someFunction(true /* remember */);
}

Namun, menggunakan enum membuat pemanggilan fungsi lebih mudah dimengerti, dengan mengorbankan beberapa kode pendukung:

public enum RememberFoo {
    REMEMBER,
    FORGET
}

...

void someFunction(RememberFoo remember);

...

void ourFunction() {
    someFunction(RememberFoo.REMEMBER);
}

Jika Anda tidak dapat mengubah tanda tangan someFunctionuntuk alasan apa pun, menggunakan variabel sementara membuat kode lebih mudah dibaca juga, semacam menyederhanakan persyaratan dengan memperkenalkan variabel tanpa alasan lain selain membuat kode lebih mudah diurai oleh manusia. .

void someFunction(boolean remember);

...

void ourFunction() {
    boolean remember = false;
    someFunction(remember);
}

Ubah nama variabel sehingga nilai bool masuk akal.

Ini sejuta kali lebih baik daripada menambahkan komentar untuk menjelaskan argumen ke suatu fungsi karena namanya ambigu.

Buat boolean lokal dengan nama yang lebih deskriptif, dan berikan nilainya. Dengan begitu maknanya akan lebih jelas.

void ourFunction() {
    bool takeAction = false;  /* false means to forget */
    someFunction( takeAction );
}    

Jika Anda tidak dapat mengubah nama variabel, maka komentar harus sedikit lebih ekspresif:

void ourFunction() {
    /* false means that the method should forget what was requested */
    someFunction( false );
}    

Ada artikel bagus yang menyebutkan situasi yang tepat ini karena merujuk ke Qt-Style APIs. Di sana, ini disebut The Boolean Parameter Trap dan layak dibaca.

Intinya adalah:

1. Kelebihan fungsi sehingga bool tidak diperlukan lebih baik
2. Menggunakan enum (seperti yang disarankan Esailija) adalah yang terbaik

Ini komentar yang aneh.

Dari perspektif kompiler, someFunction(false /* forget */);sebenarnya someFunction(false);(komentar dilucuti). Jadi, semua yang dilakukan adalah panggilan someFunctiondengan argumen pertama (dan satu-satunya) diatur ke false.

/* forget */hanya nama parameternya. Ini mungkin tidak lebih dari pengingat cepat (dan kotor), yang tidak benar-benar perlu ada di sana. Cukup gunakan nama parameter yang kurang ambigu, dan Anda tidak akan memerlukan komentar sama sekali.

Salah satu saran dari kode Bersih adalah untuk meminimalkan jumlah komentar yang tidak perlu ¹ (karena mereka cenderung membusuk), dan untuk menyebutkan fungsi dan metode dengan benar.

Setelah itu, saya hanya akan menghapus komentar. Setelah semua, IDE modern (seperti gerhana) muncul kotak dengan kode ketika Anda meletakkan mouse di atas fungsi. Melihat kode harus menghapus ambiguitas.

¹ Mengomentari beberapa kode kompleks tidak masalah.

Untuk mengelabui yang jelas, komentar bisa berbohong. Jadi selalu lebih baik untuk membuat kode mendokumentasikan diri Anda tanpa menggunakan komentar untuk menjelaskan, karena beberapa orang (mungkin Anda) akan berubah trueke falsedan tidak memperbarui komentar.

Jika Anda tidak dapat mengubah API, maka saya menggunakan 2 opsi

• Ubah komentar sehingga selalu benar, apa pun kodenya. Jika Anda hanya memanggil ini satu kali, ini adalah solusi yang baik, karena membuat dokumentasi tetap lokal.

     someFunction (false / * true = lupa, false = ingat * /); `

• Gunakan #defines, terutama jika Anda menyebutnya lebih dari sekali.

     #define FORGET true
     #define INGAT salah
     someFunction (INGAT);

Saya suka jawaban tentang membuat komentar selalu benar , tetapi sementara bagus saya pikir itu merindukan masalah mendasar dengan kode ini - itu disebut dengan literal.

Anda harus menghindari penggunaan literal saat memanggil metode. Variabel lokal, parameter opsional, parameter bernama, enum - cara terbaik Anda menghindarinya akan tergantung pada bahasa dan apa yang tersedia, tetapi cobalah untuk menghindarinya. Literal memiliki nilai, tetapi mereka tidak memiliki makna.

Di C #, saya menggunakan parameter bernama untuk membuat ini lebih jelas

someFunction(forget: false);

Atau enum:

enum Memory { Remember, Forget };

someFunction(Memory.Forget);

Atau kelebihan:

someFunctionForget();

Atau polimorfisme`:

var foo = new Elephantine();

foo.someFunction();

Penamaan harus selalu menyelesaikan ambiguitas untuk boolean. Saya selalu memberi nama boolean sesuatu seperti 'isThis' atau 'shouldDoThat', misalnya:

void printTree(Tree tree, bool shouldPrintPretty){ ... }

dan seterusnya. Tetapi ketika Anda mereferensikan kode orang lain, yang terbaik adalah meninggalkan komentar ketika memberikan nilai.