Offline Pages: add doc on SQLite column ordering and small improvements.

Bug: 701939
Change-Id: If4882e98fe2bee0c7d04df6d7f08bd1d7a67e476
Reviewed-on: https://chromium-review.googlesource.com/627516
Commit-Queue: Carlos Knippschild <carlosk@chromium.org>
Reviewed-by: Filip Gorski <fgorski@chromium.org>
Cr-Commit-Position: refs/heads/master@{#496580}

components/offline_pages/core/prefetch/stale_entry_finalizer_task.h

@@ -24,7 +24,7 @@ class StaleEntryFinalizerTask : public Task {
  public:
   using NowGetter = base::RepeatingCallback<base::Time()>;
 
-  StaleEntryFinalizerTask(PrefetchStore* prefetch_store);
+  explicit StaleEntryFinalizerTask(PrefetchStore* prefetch_store);
   ~StaleEntryFinalizerTask() override;
 
   void Run() override;

components/offline_pages/core/prefetch/store/README.md

@@ -136,3 +136,14 @@ be much better to use an enum, or a structure containing an enum, that gives a
 better detail of what went wrong.
 See `//components/offline_pages/core/prefetch/add_unique_urls_task.cc` for a
 good example of working consumer of the API.
+
+## Column ordering in table creation
+
+Column ordering is important to simplify data retrieval in SQLite 3 tables. When
+creating a table fixed-width columns should be declared first and variable-width
+ones later.
+
+Furthermore, when adding or removing columns, any existing column ordering might
+not be kept. This means that any query must not presume column ordering and must
+always explicitly refer to them by name. Using <code>SELECT * FROM ...</code>
+for obtaining data in all columns is therefore *unsafe and forbidden*.

components/offline_pages/core/prefetch/store/prefetch_store.cc

@@ -35,16 +35,16 @@ using InitializeCallback =
     base::Callback<void(InitializationStatus,
                         std::unique_ptr<sql::Connection>)>;
 
-// IMPORTANT: when making changes to these columns please also reflect them
+// IMPORTANT #1: when making changes to these columns please also reflect them
 // into:
 // - PrefetchItem: update existing fields and all method implementations
 //   (operator=, operator<<, ToString, etc).
 // - PrefetchItemTest, PrefetchStoreTestUtil: update test related code to cover
 //   the changed set of columns and PrefetchItem members.
 // - MockPrefetchItemGenerator: so that its generated items consider all fields.
-// IMPORTANT #2: the order of columns types is also important in SQLite tables
-// for optimizing space utilization. Fixed length types must come first and
-// variable length types later.
+// IMPORTANT #2: the ordering of column types is important in SQLite 3 tables to
+// simplify data retrieval. Columns with fixed length types must come first and
+// variable length types must come later.
 static const char kTableCreationSql[] =
     "CREATE TABLE prefetch_items"
     // Fixed length columns come first.