diff --git a/rules/use-clear-meaningful-names/rule.md b/rules/use-clear-meaningful-names/rule.md index 022e69397d5..27b0c8d2aaa 100644 --- a/rules/use-clear-meaningful-names/rule.md +++ b/rules/use-clear-meaningful-names/rule.md @@ -39,7 +39,7 @@ Names should always describe at first glance what something represents. ## ⚠️ Avoid mental encoding -It’s easy to invent codes to keep names short, like `cstmrMgr` to represent a "customer manager" - and you might feel clever doing it. But this kind of shorthand requires other developers (or your future self) to mentally decode each abbreviation. There’s no good reason not to simply call it `CustomerManager` (although there are reasons to avoid "manager" as a name, see [Do you avoid generic names like “manager,” “processor,” “data,” or “info”?](/avoid-generic-names)). +Keep names obvious. It’s easy to invent codes to keep names short, like `cstmrMgr` to represent a "customer manager" - and you might feel clever doing it. But this kind of shorthand requires other developers (or your future self) to mentally decode each abbreviation. There’s no good reason not to simply call it `CustomerManager` (although there are reasons to avoid "manager" as a name, see [Do you avoid generic names like “manager,” “processor,” “data,” or “info”?](/avoid-generic-names)). ## Be verbose @@ -53,14 +53,18 @@ Full, meaningful words make your code readable and maintainable. ::: :::bad Bad example - Being clever for you can cause confusion to others - they might misinterpret "energy" as something else, like power or ammo. Then if you add enemies, would you name their energy variable `nmeNrg`? -::: +::: + + :::greybox `PlayerHealth` - clearly describes the specific kind of "energy" (health) and who it belongs to (the player) ::: :::good Good example - instantly understandable to anyone reading the code -::: +::: + + Now let’s say you’re working on an invitation and activation feature. You need a variable to store the validity period for an invitation - the live time. @@ -69,30 +73,37 @@ Now let’s say you’re working on an invitation and activation feature. You ne ::: :::bad Bad example - others will have fun deciphering this one -::: +::: + + :::greybox `InvitationTimeRemainingInDays` - no explanation needed here! ::: :::good Good example - leaves no room for misinterpretation and makes the purpose obvious -::: +::: :::greybox `UserValidator` - this class is responsible for validating a user ::: :::bad Bad example - Validating what exactly? Login credentials? Profile information? Something else? -::: +::: + + :::greybox `UserValidationHandler` - indicates it’s an engine responsible for executing multiple rules to handle user-related validation + `UserNameLengthValidator` - validator is for a specific aspect of a user - the length of a username `UserEmailFormatValidator` - validator for another specific aspect - ensures email contains "@" and a domain ::: :::good Good example - the definition of the classes is in their names -::: +::: + + :::info **Remember:** Names should always describe what something represents without mental gymnastics to decode it.