Question

使用以下Action方法，在评论中描述bool的正确方法是什么？

public class MainPage : MasterDetailPage
{

    public MainPage()
    {
        Title = Strings.app_title;

        // here the Action gets injected into the constructor of the master page
        var master = new MainMenu(OnToggleRequest());
        var detail = new NavigationPage(new ModulePage { Title = Strings.app_title });

        Master = master;
        Detail = detail;
    }

    /// <summary>
    /// Toggles the Navigation Drawer
    /// </summary>
    /// <returns>An Action<bool?> where bool indicates if the Navigation Drawer Should Be Presented</returns>
    /// <remarks>If the bool is null, then the Navigation Drawer state will simply be toggled</remarks>
    private Action<bool?> OnToggleRequest()
    {
        return shouldBePresented =>
        {
            if (shouldBePresented == null)
            {
                // just switch it
                IsPresented = !IsPresented;
            }
            else
            {
                // manually set it
                IsPresented = (bool)shouldBePresented;
            }
        };
    }
}

Answer 1

我不建议在评论中描述返回值类型及其参数。这是代码中已经存在的重复信息。而是描述返回的值意味着什么。

不幸的是，我无法找到任何记录的.NET方法，它返回Action以获得良好的评论样本。通常是MSDN，当它描述这种类型的返回值时，他们只是说 Type：System.Action 。这看起来像生成的文档给我。

回到你的案子。如果您不了解方法的目的，那么很难写出解释方法目的的好评和简短评论。第一次尝试可能看起来像

/// <returns>Callback for setting whether navigation drawer should present</returns>
/// <remarks>Pass true to callback to enable drawler, false to disable drawler, or null to toggle current setting.</remarks>
private Action<bool?> OnToggleRequest()

对于我而言，长而复杂的评论就像一股气味，实际上几乎任何评论都是一种气味:)。如果你无法解释正在做什么方法，那么可能它做了太多事情，或者它不清楚什么方法在做什么。我看到您将null传递给IsPresented标志的切换值。对我来说，null的传递还不清楚。不是在你的方法中隐藏解释，而是编写注释（在你调用动作时无法访问），我会拥有属性和漂亮的自描述方法：

public bool IsDrawlerEnabled { get; set; }

public void ToggleDrawler()
{
    IsDrawlerEnabled = !IsDrawlerEnabled;
}

它还不是最好的名字，但比toggleRequest(null)要好得多。

Answer 2

＆＃34;表示是否应该出示X的标志＆＃34;

如何评论一个Action的类型参数？

2 个答案: