Implement shortcut for finalizing a trial with all remaining probability...

base/field_trial.h

-// Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
+// Copyright (c) 2006-2009 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.
 
 // FieldTrial is a class for handling details of statistical experiments
 // performed by actual users in the field (i.e., in a shipped or beta product).
 // All code is called exclusively on the UI thread currently.
 //
 // The simplest example is an experiment to see whether one of two options
 // produces "better" results across our user population.  In that scenario, UMA
 // data is uploaded to aggregate the test results, and this FieldTrial class
@@ skipping 31 matching lines @@
 //   SetMemoryModel(LOW);  // Sample alternate setting.
 
 // We then modify any histograms we wish to correlate with our experiment to
 // have slighly different names, depending on what group the trial instance
 // happened (randomly) to be assigned to:
 
 // HISTOGRAM_COUNTS(FieldTrial::MakeName("Memory.RendererTotal",
 //                                       "MemoryExperiment").data(), count);
 
 // The above code will create 3 distinct histograms, with each run of the
-// application being assigned to of of teh three groups, and for each group, the
+// application being assigned to of of the three groups, and for each group, the
 // correspondingly named histogram will be populated:
 
 // Memory.RendererTotal            // 96% of users still fill this histogram.
 // Memory.RendererTotal_high_mem   // 2% of users will fill this histogram.
 // Memory.RendererTotal_low_mem    // 2% of users will fill this histogram.
 
 //------------------------------------------------------------------------------
 
 #ifndef BASE_FIELD_TRIAL_H_
 #define BASE_FIELD_TRIAL_H_
 
 #include <map>
 #include <string>
 
 #include "base/lock.h"
 #include "base/ref_counted.h"
 #include "base/time.h"
 
 
 class FieldTrial : public base::RefCounted<FieldTrial> {
  public:
   typedef int Probability;  // Probability type for being selected in a trial.
 
   // A return value to indicate that a given instance has not yet had a group
   // assignment (and hence is not yet participating in the trial).
   static const int kNotParticipating;
 
   // Provide an easy way to assign all remaining probability to a group.  Note
   // that this will force an instance to participate, and make it illegal to
-  // attempt to probabalistically add any other groups to the trial.
+  // attempt to probabalistically add any other groups to the trial.  When doing
+  // A/B tests with timings, it is often best to define all groups, so that
+  // histograms will get unique names via the MakeName() methods.
   static const Probability kAllRemainingProbability;
 
   // The name is used to register the instance with the FieldTrialList class,
   // and can be used to find the trial (only one trial can be present for each
   // name).
   // Group probabilities that are later supplied must sum to less than or equal
   // to the total_probability.
   FieldTrial(const std::string& name, Probability total_probability);
 
   // Establish the name and probability of the next group in this trial.
@@ skipping 121 matching lines @@
 
   // Lock for access to registered_.
   Lock lock_;
   RegistrationList registered_;
 
   DISALLOW_COPY_AND_ASSIGN(FieldTrialList);
 };
 
 #endif  // BASE_FIELD_TRIAL_H_