From 995154239358af589146ab4697e7cb4f100e2d84 Mon Sep 17 00:00:00 2001
From: Erik Johnston <erik@matrix.org>
Date: Tue, 5 May 2015 17:06:55 +0100
Subject: [PATCH] Add a comment about the zip(*[zip(sorted(...),...)])

---
 synapse/storage/_base.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/synapse/storage/_base.py b/synapse/storage/_base.py
index b7c3cf03c..94946587f 100644
--- a/synapse/storage/_base.py
+++ b/synapse/storage/_base.py
@@ -453,6 +453,14 @@ class SQLBaseStore(object):
         if not values:
             return
 
+        # This is a *slight* abomination to get a list of tuples of key names
+        # and a list of tuples of value names.
+        #
+        # i.e. [{"a": 1, "b": 2}, {"c": 3, "d": 4}]
+        #         => [("a", "b",), ("c", "d",)] and [(1, 2,), (3, 4,)]
+        #
+        # The sort is to ensure that we don't rely on dictionary iteration
+        # order.
         keys, vals = zip(*[
             zip(
                 *(sorted(i.items(), key=lambda kv: kv[0]))