diff options
Diffstat (limited to 'docs/development/submitting-patches.rst')
| -rw-r--r-- | docs/development/submitting-patches.rst | 15 |
1 files changed, 10 insertions, 5 deletions
diff --git a/docs/development/submitting-patches.rst b/docs/development/submitting-patches.rst index 66105843..ac1986a3 100644 --- a/docs/development/submitting-patches.rst +++ b/docs/development/submitting-patches.rst @@ -48,7 +48,7 @@ API considerations Most projects' APIs are designed with a philosophy of "make easy things easy, and make hard things possible". One of the perils of writing cryptographic code is that secure code looks just like insecure code, and its results are almost -always indistinguishable. As a result ``cryptography`` has, as a design +always indistinguishable. As a result, ``cryptography`` has, as a design philosophy: "make it hard to do insecure things". Here are a few strategies for API design that should be both followed, and should inspire other API choices: @@ -126,6 +126,11 @@ should begin with the "Hazardous Materials" warning: .. hazmat:: +Always prefer terminology that is most broadly accepted. For example: + +* When referring to class instances use "an instance of ``Foo``" + instead of "a ``Foo`` provider". + When referring to a hypothetical individual (such as "a person receiving an encrypted message") use gender neutral pronouns (they/them/their). @@ -149,8 +154,8 @@ So, specifically: * Use Sphinx parameter/attribute documentation `syntax`_. -.. _`Write comments as complete sentences.`: http://nedbatchelder.com/blog/201401/comments_should_be_sentences.html -.. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists -.. _`Studies have shown`: https://smartbear.com/smartbear/media/pdfs/wp-cc-11-best-practices-of-peer-code-review.pdf +.. _`Write comments as complete sentences.`: https://nedbatchelder.com/blog/201401/comments_should_be_sentences.html +.. _`syntax`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists +.. _`Studies have shown`: https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/ .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev -.. _`doc8`: https://github.com/stackforge/doc8 +.. _`doc8`: https://github.com/openstack/doc8 |