From c78ccb3dcb52c15b5177f19fa92fa97750e11b70 Mon Sep 17 00:00:00 2001
From: Guido van Rossum <guido@python.org>
Date: Mon, 13 Feb 2017 21:50:40 -0800
Subject: [PATCH] Clarify my preferences around trailing commas (#211)

---
 pep-0008.txt | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/pep-0008.txt b/pep-0008.txt
index 381cb690b..97f07f8b8 100644
--- a/pep-0008.txt
+++ b/pep-0008.txt
@@ -466,6 +466,11 @@ Avoid extraneous whitespace in the following situations:
       Yes: spam(ham[1], {eggs: 2})
       No:  spam( ham[ 1 ], { eggs: 2 } )
 
+- Between a trailing comma and a following close parentheses. ::
+
+      Yes: foo = (0,)
+      No:  bar = (0, )
+
 - Immediately before a comma, semicolon, or colon::
 
       Yes: if x == 4: print x, y; x, y = y, x
@@ -637,6 +642,47 @@ Other Recommendations
 
       if foo == 'blah': one(); two(); three()
 
+When to use trailing commas
+===========================
+
+Trailing commas are usually optional, except they are mandatory when
+making a tuple of one element (and in Python 2 they have semantics for
+the ``print`` statement).  For clarity, it is recommended to surround
+the latter in (technically redundant) parentheses.
+
+  Yes::
+
+      FILES = ('setup.cfg',)
+
+  OK, but confusing::
+
+      FILES = 'setup.cfg',
+
+When trailing commas are redundant, they are often helpful when a
+version control system is used, when a list of values, arguments or
+imported items is expected to be extended over time.  The pattern is
+to put each value (etc.) on a line by itself, always adding a trailing
+comma, and add the close parenthesis/bracket/brace on the next line.
+However it does not make sense to have a trailing comma on the same
+line as the closing delimiter (except in the above case of singleton
+tuples).
+
+  Yes::
+
+      FILES = [
+          'setup.cfg',
+          'tox.ini',
+          ]
+      initialize(FILES,
+                 error=True,
+                 )
+
+  No::
+
+      FILES = ['setup.cfg', 'tox.ini',]
+      initialize(FILES, error=True,)
+
+
 Comments
 ========