Document partner showcase sequence generation

website/partners/context_processors.py

@@ -4,6 +4,15 @@ from partners.models import Partner
 
 
 def showcased_partners(request):
+    """
+    Generate a sequence of showcased partners (banners)
+
+    For each user we generate a sequence of banners. This sequence
+    is then stored for that user, because doing it randomly creates
+    a feel of an artificial 'bias' towards certain sponsors. Doing
+    it this way ensures that everyone gets an exactly fair number of
+    views.
+    """
     all_partners = Partner.objects.filter(is_active=True).order_by('id')
     ids = [partner.id for partner in all_partners]
 
@@ -11,6 +20,7 @@ def showcased_partners(request):
     if ('partner_sequence' not in request.session or
             'partner_ids' not in request.session or
             request.session['partner_ids'] != ids):
+        # Store a list of partner ids to allow checking for changes in partners
         request.session['partner_ids'] = ids
         request.session['partner_sequence'] = sample(ids, len(ids))