Merge pull request #566 from alex/comment-cleanup

Write comments as complete sentences

2 files changed, 11 insertions, 6 deletions

diff --git a/cryptography/hazmat/bindings/openssl/binding.py b/cryptography/hazmat/bindings/openssl/binding.py
index cde3bdbd..3adcc887 100644
--- a/cryptography/hazmat/bindings/openssl/binding.py
+++ b/cryptography/hazmat/bindings/openssl/binding.py
@@ -86,7 +86,8 @@ class Binding(object):
         if cls.ffi is not None and cls.lib is not None:
             return
 
-        # platform check to set the right library names
+        # OpenSSL goes by a different library name on different operating
+        # systems.
         if sys.platform != "win32":
             libraries = ["crypto", "ssl"]
         else:  # pragma: no cover
@@ -98,7 +99,8 @@ class Binding(object):
 
     @classmethod
     def is_available(cls):
-        # OpenSSL is the only binding so for now it must always be available
+        # For now, OpenSSL is considered our "default" binding, so we treat it
+        # as always available.
         return True
 
     @classmethod
@@ -112,15 +114,15 @@ class Binding(object):
                     cls._lock_cb
                 )
 
-            # use Python's implementation if available
-
+            # Use Python's implementation if available, importing _ssl triggers
+            # the setup for this.
             __import__("_ssl")
 
             if cls.lib.CRYPTO_get_locking_callback() != cls.ffi.NULL:
                 return
 
-            # otherwise setup our version
-
+            # If nothing else has setup a locking callback already, we set up
+            # our own
             num_locks = cls.lib.CRYPTO_num_locks()
             cls._locks = [threading.Lock() for n in range(num_locks)]
 
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 74b854bd..7f4c77f4 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -43,6 +43,8 @@ Code
 
 When in doubt, refer to :pep:`8` for Python code.
 
+`Write comments as complete sentences.`_
+
 Every code file must start with the boilerplate notice of the Apache License.
 Additionally, every Python code file must contain
 
@@ -287,6 +289,7 @@ The HTML documentation index can now be found at
 
 .. _`GitHub`: https://github.com/pyca/cryptography
 .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev
+.. _`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
 .. _`pytest`: https://pypi.python.org/pypi/pytest
 .. _`tox`: https://pypi.python.org/pypi/tox