chore(docs): Suggestions for the docstring guide in CONTRIBUTING#5
Conversation
Clarify the prohibition on including constant values in docstrings by replacing the parenthetical "(not verbatim and not a decomposition)" with more precise language.
0c6cb2b to
2227cdb
Compare
Relabel "Good" to "Acceptable" for the literal expression example, reword the composition guidance, add explanations for each example tier, and fix TX_MAS_GAS typo.
- Reorder bullets to lead with positive guidance and group "don'ts" at the end. - Add one-line vs multi-line preference with examples. - Add reference-style link example for EIP references.
- Move the imperative mood bullet from the Functions subsection into the top-level docstring list, next to the one-liner preference. - Remove the now-empty Functions subsection. # Conflicts: # CONTRIBUTING.md
2227cdb to
d098e72
Compare
| - Don't begin with an article ("the"/"a") or a pronoun ("it", "they", etc.). | ||
| - Write in complete sentences, providing background and context for the associated code. | ||
| - Link to relevant standards/EIPs. | ||
| - Prefer a one-line summary when possible. Use a multi-line docstring with a blank line after the summary when more detail is needed. |
There was a problem hiding this comment.
Is this suggesting:
- Prefer a one-line summary over a multiple line summary; or
- Prefer a one-line summary over a multi-line docstring?
There was a problem hiding this comment.
This wasn't very clear, thanks. Updated!
| - Don't begin with an article ("the"/"a") or a pronoun ("it", "they", etc.). | ||
| - Don't include the function's signature. | ||
|
|
||
| ##### Constants |
There was a problem hiding this comment.
Why keep the constants section if we're dropping functions?
There was a problem hiding this comment.
Functions seemed short and relevant enough to put in the top-level list. Constants seemed too large to move up.
I've moved the function imperative rule below
- Write in complete sentences,
as this seems to be a better flow.
| - **Good:** Build the house using the provided lumber. | ||
| - **Bad:** Builds the house using the provided lumber. | ||
| - Format using markdown. | ||
| - Link to relevant standards and EIPs using reference-style links. |
There was a problem hiding this comment.
Do we care what style the links are? I end up using this style because it's easier to avoid the line length limit, but I don't feel strongly about it.
There was a problem hiding this comment.
No, I don't have a strong opinion on this, I've softened the formulation. But reference-style links do help readability in the source.
| - Write function and method docstrings in the imperative mood. | ||
| - **Good:** Build the house using the provided lumber. | ||
| - **Bad:** Builds the house using the provided lumber. |
There was a problem hiding this comment.
Do we want the entire docstring in imperative mood? I fear that might be sound awkward for long annotations that go deeper into the background/context for a function.
There was a problem hiding this comment.
Agreed that whole docstrings in the imperative is awkward. Updated for clarity.
|
|
||
| ```python | ||
| # EIP-1234: The dingus is the rate of fleep | ||
| # EIP-1234: The dingus is the rate of fleep |
There was a problem hiding this comment.
I even left a comment explaining the trailing whitespace! 😾
Hey Sam, I thought I'd PR my suggestions to ethereum#2195 here.
I additionally re-ordered the top-level "Docstring" section bullet points for clarity and moved the point about "imperative style for functions" next to the "good one-liner" advice in the top-level bullet points (they both address how to write summary lines, at least for functions).
Cute Animal Picture