2510C++,api设计原则,不除零

原文

`API`设计原则:不引诱人除以零

一个团队正带来一个API以供审查,其中一个部分涉及以三个数字表达一组支持的值:

1,允许的最小值.

2,增量.

3,允许的最大值.

支持的值是增量与最小值相加的最小值整数倍,最多(包括最大值).

如,如果最小值为5,增量为10,最大值为30,则有效值为

cpp 复制代码

5|Minimum
15|Minimum + 1 * Increment
25|Minimum + 2 * Increment
30|Maximum

该团队还说明,如果增量为零,则只支持最小值和最大值.

我说明,该设计会诱使用户除零.

这是你可能编写的函数:

cpp 复制代码

int closestSupportedValue(int desired)
{
    int nearest = minimum +
        ((desired - minimum + increment/2) / increment) * increment;
    return std::clamp(nearest, minimum, maximum);
}

首先找到超出最接近要求值的最小值的增量倍数.,可通过适当更改及增量/2来圆整.然后在允许的范围内限制该值.

除非增量为零,否则这很有效.如,你可能在所有测试中都不会遇见零,因为他们测试代码的所有硬件都支持广泛的可能值.

他们从未意识到必须在仅支持1或2个可能值的硬件上测试.

我建议团队从API中删除零.如果仅支持两个值,则按等于最大值-最小值设置增量.如果仅支持一个值,则按1设置增量.

:电网团队落入了该陷阱.PowerGridForecast类表示一系列从StartTime开始,每个预测表示BlockDuration描述的时间长度的PowerGridData对象.

即,向量的第n个符号表示从StartTime+n*BlockDuration开始,并持续到BlockDuration的预测.

要编写一个查找描述特定时间点的块的函数,可如下:

cpp 复制代码

PowerGridData FindForecastForDateTime(
    PowerGridForecast forecast, DateTime time)
{
    var elapsed = time - forecast.StartTime;
    var index = elapsed / forecast.BlockDuration;
    if (index < 0 || index >= forecast.Forecast.Count) {
        return null;
    //该索引没有预测
    }
    return forecast.Forecast[index];
}

确定自第一次预测开始以来经过的时间,确定它属于哪个块索引,(如果有)并返回该索引处的符号.

该团队决定,如果没有预测,则Forecast属性将返回一个空向量(良好),而BlockDuration将为零(坏).

该团队认为,如果没有预测,区块大小就不重要,因为它描述的是不存在的东西,所以谁在乎它是否为零,但在上面看到,零区块持续时间表明索引的计算执行除零计算.

因为区块大小不重要,他们应该选择一个不太可能引起问题的值.选择一个典型有效块大小,如一小时的非零块大小.

实际上,可按大于最大值-最小值的任何正值设置增量,尽管不想选择太大的值,因为这有整数溢出的风险.

2510C++,api设计原则,不除零

API设计原则:不引诱人除以零

`API`设计原则:不引诱人除以零