Skip to content

Commit 86a969f

Browse files
committed
Reframe type names guide to allow more judgement
Incorporating suggestions from @nedbat and @encukou, this change: - updates the first paragraph to be less absolute and deliver some context by adding "indicate the name is a type by..." - refocuses the last paragraph to use `dict` as an example and allow for mixed usage once the class under discussion is clear - moves the note on lowercasing names out to a short trailer, and introduces the idea that this rule is correct because these names are not proper nouns
1 parent 81deaa3 commit 86a969f

1 file changed

Lines changed: 11 additions & 7 deletions

File tree

documentation/style-guide.rst

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -148,9 +148,10 @@ Unix
148148
Type names
149149
==========
150150

151-
When writing the names of types in prose, write the name of the type
152-
exactly as it appears in source, styled as a class reference or an unlinked
153-
class. For example, refer to dict as ``:class:`dict`‌`` or ``:class:`!dict`‌``.
151+
When writing the names of types in prose, indicate that the name is a type by
152+
writing the name of the type exactly as it appears in source, styled as a class
153+
reference or an unlinked class. For example, refer to dict as ``:class:`dict`‌``
154+
or ``:class:`!dict`‌``.
154155

155156
Links should be used according to the :ref:`guidance on links <style-guide-links>`.
156157

@@ -159,12 +160,15 @@ For example, "tuples" are a general programming concept, as distinct from the
159160
``tuple`` type. When referring to general ideas, do not style the relevant word
160161
as a type.
161162

162-
Many types have descriptive names which do not exactly match their type
163+
Many types have descriptive names which may or may not exactly match their type
163164
name. For example, "context variables" describes ``contextvars.ContextVar``,
164-
and "partial function" may be used to describe an application of
165-
``functools.partial``. Use these names only when they serve to clarify the text
166-
better than the type name itself would, and put them in lowercase.
165+
and both "dict" and "dictonary" are used to describe ``dict``. Once it is clear
166+
that the text refers to a specific type, use the naming which suits the context:
167+
in the case of ``dict``, any of "dict", "dictionary", or "``:class:`dict```" may
168+
be best.
167169

170+
Descriptive names should be written as common nouns, meaning they are lowercase
171+
when not at the start of a sentence or phrase.
168172

169173
.. index:: diataxis
170174
.. _diataxis:

0 commit comments

Comments
 (0)