Nhận xét đúng để đặt cho các đối số hàm boolean là Sai false?

Từ một số dự án nguồn mở, tôi đã thu thập kiểu mã hóa sau

void someFunction(bool forget);

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

Tôi luôn nghi ngờ về những gì falsecó nghĩa là ở đây. Liệu nó có nghĩa là "quên", hay "quên" đề cập đến tham số tương ứng của nó (như trong trường hợp trên) và "false" có nghĩa là phủ nhận nó?

Phong cách nào được sử dụng thường xuyên nhất và cách tốt nhất (hoặc một số cách tốt hơn) để tránh sự mơ hồ là gì?

Trong mã mẫu bạn đã đăng, có vẻ như forgetlà một đối số cờ. (Tôi không thể chắc chắn vì chức năng hoàn toàn là giả thuyết.)

Đối số cờ là một mùi mã. Chúng chỉ ra rằng một chức năng làm nhiều hơn một việc, và một chức năng tốt chỉ nên làm một việc.

Để tránh đối số cờ, chia hàm thành hai hàm giải thích sự khác biệt trong tên hàm.

Đối số cờ

serveIceCream(bool lowFat)

Không có đối số cờ

serveTraditionalIceCream()
serveLowFatIceCream()

chỉnh sửa: Lý tưởng nhất là bạn không cần phải giữ một chức năng với tham số cờ. Có những trường hợp dọc theo dòng mà Fowler gọi là một triển khai rối trong đó việc tách hoàn toàn các hàm tạo ra mã trùng lặp. Tuy nhiên, độ phức tạp chu kỳ của hàm được tham số hóa càng cao thì đối số để loại bỏ nó càng mạnh.

Theo cách nói của giáo dân:

• false là một nghĩa đen.
• bạn đang vượt qua một nghĩa đen false
• bạn đang nói someFunctionđừng quên
• bạn đang nói someFunctionrằng tham số quên làfalse
• bạn đang nói someFunctionđể nhớ

Theo tôi sẽ tốt hơn nếu chức năng như thế này:

void someFunction(bool remember);

bạn có thể gọi nó

void ourFunction() {
  someFunction(true);
} 

hoặc giữ tên cũ nhưng thay đổi chức năng trình bao bọc của bạn thành

void ourFunctionWithRemember() {
  someFunction(false);
} 

CHỈNH SỬA:

Như @Vorac đã nêu, luôn cố gắng sử dụng những từ tích cực. Phủ định kép là khó hiểu.

Tham số có thể được đặt tên tốt; thật khó để nói mà không biết tên của hàm. Tôi cho rằng những nhận xét được viết bởi tác giả ban đầu của hàm, và đó là một lời nhắc nhở về những gì đi falsevào someFunctionphương tiện, nhưng đối với bất cứ ai đến cùng sau đó, đó là một chút không rõ ràng ở cái nhìn đầu tiên.

Sử dụng tên biến tích cực (được đề xuất trong Hoàn thành mã ) có thể là thay đổi đơn giản nhất giúp đoạn mã này dễ đọc hơn, ví dụ:

void someFunction(boolean remember);

sau đó ourFunctiontrở thành:

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

Tuy nhiên, việc sử dụng enum làm cho hàm gọi trở nên dễ hiểu hơn, với chi phí của một số mã hỗ trợ:

public enum RememberFoo {
    REMEMBER,
    FORGET
}

...

void someFunction(RememberFoo remember);

...

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

Nếu bạn không thể thay đổi chữ ký someFunctionvì bất kỳ lý do gì, sử dụng biến tạm thời cũng giúp mã dễ đọc hơn, giống như đơn giản hóa các điều kiện bằng cách đưa ra một biến không vì lý do nào khác ngoài việc làm cho mã dễ phân tích hơn bởi con người .

void someFunction(boolean remember);

...

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

Đổi tên biến để giá trị bool có ý nghĩa.

Điều này tốt hơn một triệu lần so với việc thêm một nhận xét để giải thích các đối số cho một hàm vì tên này không rõ ràng.

Tạo một boolean cục bộ với một tên mô tả nhiều hơn và gán giá trị cho nó. Bằng cách đó, ý nghĩa sẽ rõ ràng hơn.

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

Nếu bạn không thể đổi tên biến, thì bình luận nên biểu cảm hơn một chút:

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

Có một bài viết hay đề cập đến tình huống chính xác này khi đề cập đến API kiểu Qt. Ở đó, nó được gọi là Bẫy thông số Boolean và nó đáng để đọc.

Ý chính của nó là:

1. Quá tải hàm để bool không cần thiết là tốt hơn
2. Sử dụng một enum (như Esailija gợi ý) là tốt nhất

Đây là một bình luận kỳ quái.

Từ quan điểm của nhà soạn nhạc, someFunction(false /* forget */);thực sự someFunction(false);(bình luận bị tước bỏ). Vì vậy, tất cả dòng đó là cuộc gọi someFunctionvới đối số đầu tiên (và duy nhất) được đặt thành false.

/* forget */chỉ là tên của tham số. Có lẽ không có gì hơn là một lời nhắc nhở nhanh chóng (và bẩn thỉu), mà thực sự không cần phải ở đó. Chỉ cần sử dụng một tên tham số ít mơ hồ hơn và bạn sẽ không cần bình luận gì cả.

Một trong những lời khuyên của Clean code là giảm thiểu số lượng bình luận không cần thiết ¹ (vì chúng có xu hướng bị thối) và đặt tên cho các hàm và phương thức đúng cách.

Sau đó, tôi sẽ chỉ cần xóa bình luận. Rốt cuộc, các IDE hiện đại (như nhật thực) bật một hộp có mã khi bạn đặt chuột lên hàm. Xem mã nên xóa sự mơ hồ.

¹ Nhận xét một số mã phức tạp là ok.

Để tin vào sự rõ ràng, ý kiến ​​có thể nói dối. Do đó luôn luôn là tốt hơn để làm cho mã tự tài liệu của bạn mà không cần đến ý kiến để giải thích, bởi vì một số người (có lẽ bạn) sẽ thay đổi trueđể falsekhông cần cập nhật các nhận xét.

Nếu bạn không thể thay đổi API, thì tôi sử dụng 2 tùy chọn

• Thay đổi nhận xét để nó luôn luôn đúng, bất kể mã. Nếu bạn chỉ gọi điều này một lần, đây là một giải pháp tốt, vì nó giữ tài liệu cục bộ.

     someF rối (false / * true = quên, false = nhớ * /); `

• Sử dụng #defines, đặc biệt nếu bạn gọi nó nhiều lần.

     #define FORGET đúng
     #define NHỚ sai
     một số chức năng (NHỚ);

Tôi thích câu trả lời về việc làm cho nhận xét luôn luôn đúng , nhưng trong khi tốt, tôi nghĩ rằng nó bỏ lỡ vấn đề cơ bản với mã này - nó được gọi bằng một nghĩa đen.

Bạn nên tránh sử dụng chữ khi gọi phương thức. Biến cục bộ, tham số tùy chọn, tham số được đặt tên, enums - cách tốt nhất bạn tránh chúng sẽ phụ thuộc vào ngôn ngữ và những gì có sẵn, nhưng hãy cố gắng tránh chúng. Văn học có giá trị, nhưng chúng không có ý nghĩa.

Trong C #, tôi đã sử dụng các tham số được đặt tên để làm cho điều này rõ ràng hơn

someFunction(forget: false);

Hoặc enum:

enum Memory { Remember, Forget };

someFunction(Memory.Forget);

Hoặc quá tải:

someFunctionForget();

Hoặc đa hình`:

var foo = new Elephantine();

foo.someFunction();

Việc đặt tên phải luôn luôn giải quyết sự mơ hồ cho booleans. Tôi luôn đặt tên boolean một cái gì đó như 'is This' hoặc 'ShouldDoThat', ví dụ:

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

vân vân Nhưng khi bạn đang tham chiếu mã của người khác, tốt nhất chỉ nên để lại nhận xét khi truyền giá trị.