diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index 6b0d68d3b..944771dab 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -296,13 +296,13 @@ Contributors should strike a balance between commenting "too much" and commentin
 
 Human judgment and creativity must be used to create good comments, which convey important information with small amounts of text. There is no single rule which can determine what a good comment is. Longer comments are *not* always better, since needlessly long comments have a cost: they require the reader to read more, take up whitespace, and take longer to write and review.
 
-#### Don't Restate the Object Names
+#### Don't Restate the Function Names
 
-The contracts of functions should be implemented precisely enough that tests could be written looking only at the declaration and the comments. However, the
+The contracts of functions should be implemented precisely enough that tests could be written looking only at the declaration and the comments. However:
 
-* **author should assume that the reader has already read and understood the function name, variable names, type names, etc.**
+* **the author should assume that the reader has already read and understood the function name, variable names, type names, etc.**
 
-So, if a function and its variables have such descriptive names, then there may be nothing to add in the comments at all!
+So, if a function and its variables have very descriptive names, then there may be nothing to add in the comments at all!
 
 **Bad Example**
 
@@ -311,7 +311,19 @@ So, if a function and its variables have such descriptive names, then there may
 fn append_transaction_to_block(transaction:Transaction, &mut Block) -> Result<()>
 ```
 
-This is considered bad because the function already says "append transaction to block", so it doesn't add anything to restate it in the comments. However, *do* add anything that is not redundant, such as what conditions will lead to an error.
+This is considered bad because the function already says "append transaction to block", so it doesn't add anything to restate it in the comments. However, *do* add anything that is not redundant, such as elaborating what it means to "append" (if there is more to say), or what conditions will lead to an error.
+
+**Good Example**
+
+```
+/// # Errors
+///
+/// - BlockTooBigError: Is returned if adding `transaction` to `block` results
+/// in a block size bigger than MAX_BLOCK_SIZE.
+fn append_transaction_to_block(transaction:Transaction, block:&mut Block) -> Result<()>
+```
+
+This is considered good because the reader builds on the context created by the function and variable names. Rather than restating them, the function just adds elements of the contract that are not implicit in the declaration. 
 
 #### Do's and Dont's