Comment on UMA_HISTOGRAM_ENUMERATION that explains an overflow bucket

base/metrics/histogram_macros.h

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_METRICS_HISTOGRAM_MACROS_H_
 #define BASE_METRICS_HISTOGRAM_MACROS_H_
 
 #include "base/atomicops.h"
 #include "base/logging.h"
 #include "base/metrics/histogram.h"
@@ skipping 127 matching lines @@
 
 #define LOCAL_HISTOGRAM_COUNTS_10000(name, sample) \
     LOCAL_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 10000, 50)
 
 #define LOCAL_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
         base::Histogram::FactoryGet(name, min, max, bucket_count, \
                                     base::HistogramBase::kNoFlags))
 
 // This is a helper macro used by other macros and shouldn't be used directly.
+// One additional bucket is created in the LinearHistogram for the illegal
+// values >= boundary_value so that mistakes in calling the UMA enumeration
+// macros can be detected.
 #define HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary, flag) \
     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
         base::LinearHistogram::FactoryGet(name, 1, boundary, boundary + 1, \
             flag))
 
 #define LOCAL_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \
     LOCAL_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101)
 
 #define LOCAL_HISTOGRAM_BOOLEAN(name, sample) \
     STATIC_HISTOGRAM_POINTER_BLOCK(name, AddBoolean(sample), \
         base::BooleanHistogram::FactoryGet(name, base::Histogram::kNoFlags))
 
 // Support histograming of an enumerated value.  The samples should always be
 // strictly less than |boundary_value| -- this prevents you from running into
 // problems down the line if you add additional buckets to the histogram.  Note
 // also that, despite explicitly setting the minimum bucket value to |1| below,
 // it is fine for enumerated histograms to be 0-indexed -- this is because
-// enumerated histograms should never have underflow.
+// enumerated histograms should never have underflow. One additional bucket is
+// created in the LinearHistogram for the illegal values >= boundary_value so
+// that mistakes in calling this macro can be detected.
 #define LOCAL_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \
     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
         base::LinearHistogram::FactoryGet(name, 1, boundary_value, \
             boundary_value + 1, base::HistogramBase::kNoFlags))
 
 // Support histograming of an enumerated value. Samples should be one of the
 // std::vector<int> list provided via |custom_ranges|. See comments above
 // CustomRanges::FactoryGet about the requirement of |custom_ranges|.
 // You can use the helper function CustomHistogram::ArrayToCustomRanges to
 // transform a C-style array of valid sample values to a std::vector<int>.
@@ skipping 113 matching lines @@
         UMA_HISTOGRAM_LONG_TIMES_100(name, elapsed); \
       } else { \
         UMA_HISTOGRAM_TIMES(name, elapsed); \
       } \
     } \
    private: \
     base::TimeTicks constructed_; \
   } scoped_histogram_timer_##key
 
 #endif  // BASE_METRICS_HISTOGRAM_MACROS_H_