Skip to content

Commit

Permalink
update rule for CTF (#9617)
Browse files Browse the repository at this point in the history
Update rule.md
  • Loading branch information
sethdaily authored Nov 28, 2024
1 parent c94d3df commit b874c3c
Showing 1 changed file with 10 additions and 10 deletions.
20 changes: 10 additions & 10 deletions rules/verbs-for-method-names/rule.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,29 +34,29 @@ Code becomes easier to understand when names align closely with their meaning. S
A verb is a word that describes an action or process—something that’s done. Examples include walk, run, think, listen, and breathe, as well as process, calculate, send, and save. While your method names shouldn’t all be single verbs (since that’s often too vague), they should be verb-based, using a verb as the foundation of their meaning.

:::greybox
Imagine you’re working on an e-commerce app and need to write code to handle shipping products to customers who have completed an order. You create a method called `Ship`. While Ship is a verb, it’s also a noun, making it ambiguous. Additionally, it’s not descriptive enough to convey the method’s purpose clearly.
`Ship` - A method to initiate shipping orders to customers.
:::
:::bad
A method represents an action, so naming it like a thing will cause confusion
Bad example - While 'ship' is a verb, it’s also a noun, making it ambiguous. Plus, it's not very descriptive!
:::

:::greybox
A better name for this method is `SendCustomerOrder`. It’s specific, making it clear what the method does and within what context.
`SendCustomerOrder`
:::
:::good
A method that is named as a verb clearly tells you that it does something, and what that thing is
:::
Good example - A method that is named as a verb clearly tells you that it does something (sends), and what that thing is (a customer order)
:::

:::greybox
Suppose you’re working on an electronic medical record system, and you need to create a way for nurses to document medications that have been administered to patients. You name the method `Administration`. This is problematic for two reasons — it’s a noun, and it’s ambiguous. “Administration” has multiple meanings, and the method name doesn’t make it clear what this action involves.
`Administration` - a method name for nurses to document medications that have been administered to patients
:::
:::bad
A method that not only isn't a clear action, but uses a word that needs context (and none is provided) is guaranteed to cause confusion
:::
Bad example - it’s a noun, and it’s ambiguous. 'Administration' has multiple meanings, and the method name doesn’t make it clear what this action involves
:::

:::greybox
A more precise name for this method is `AdministerMedication`. It clearly describes the real-world action it models. Another option could be `RecordMedication`, but this is less effective. First, “record” can be either a noun or a verb, and second, it lacks context — it could imply logging delivery to a pharmacy or entering a new medication type into the system.
`AdministerMedication` - the action is clear
:::
:::good
Method names that describe the action and provide any needed context help avoid confusion
Good example - Method name describes the action
:::

0 comments on commit b874c3c

Please sign in to comment.