Adding terminology for magic literals #59
Conversation
|
@dimadeveatii could you kindly review this 😄 ? |
README.md
Outdated
|
|
||
| ```ts | ||
| // Declare them as capitalized named constants. | ||
| // Declare them as capitalized symbolic constants. |
There was a problem hiding this comment.
How is symbolic constants better than named constants? The use of term symbolic might confuse people to use Symbol, which is not the intention.
There was a problem hiding this comment.
The term symbolic constants is widely used throughout SE. However, seeing your next comment I do understand that the intention is to have a more straight-forward way for beginners to better get up to speed.
Is there any way we can incorporate both ? Something like the below for instance (might also help someone do further research on the term / get more familiar with):
// Declare them as capitalized symbolic constants (also known as symbolic constants).
There was a problem hiding this comment.
The term symbolic constant is more oftenly used in C/C++, you would rarely see it in a JS/TS reference. It is also mentioned as literal constant in other places. I prefer to keep it simple and not confuse the reader with too much terminology.
There was a problem hiding this comment.
Addressed on 36d14bf
README.md
Outdated
| ### Use searchable names / Avoid Magic Literals | ||
|
|
||
| We will read more code than we will ever write. It's important that the code we do write must be readable and searchable. By *not* naming variables that end up being meaningful for understanding our program, we hurt our readers. Make your names searchable. Tools like [ESLint](https://typescript-eslint.io/) can help identify unnamed constants. | ||
| We will read more code than we will ever write. It's important that the code we do write must be readable and searchable. By *not* naming variables that end up being meaningful for understanding our program, we hurt our readers. Make your names searchable. Tools like [ESLint](https://typescript-eslint.io/) can help identify magic literals. |
There was a problem hiding this comment.
The term searchable names is just what it says and it's easy to understand for a beginner who's not yet comfortable with all of the programming dictionary. While you say magic literals, others call them magic strings.
I consider the term searchable names less confusing and easier to understand for someone who is a beginner.
I do appreciate your contribution, and I'd suggest that we add it to the end of the paragraph instead:
...can help identify unnamed constants (also known as magic literals and magic strings).
There was a problem hiding this comment.
And in the end, the name searchable names is referenced in the original Clean Code book (see Chapter 2, page 22 - Use Searchable Names).
There was a problem hiding this comment.
Good point - the terminology for magic literals referes to both magic numbers and magic strings. Indeed though someone might be overwhelmed by this terminology.
Addressed this as per the above comments, explicitly mentioning magic numbers and magic strings and bringing back the unnamed constants on d1e2cfb
- Removed "/Avoid magic literals" from the header to avoid noise. - Added back unnamed constants and kept magic strings, magic numbers as a note at the end of the paragraph.
2 participants
Terminology for magic literals might be beneficial, in a sense that will make a strong impression to people and will be remembered when writing/reviewing code.
Also allows easier communication between peers, since the terminology used is an industry standard (everybody will know what the discussion is about, when it comes to magic literals, magic numbers, magic strings).