StyleGuides
Avoid duplicating object class in its name
Add to guide:
When naming an object, avoid duplicating the object's class in its name. Use the noun that follows the object name to indicate its class.
Example to avoid:
"Create the instance in the prod-environment environment."
Preferred alternative:
"Create the instance in the prod environment."
Before this goes anywhere we need to get resolution to https://github.com/RedHatTraining/skeleton/discussions/362
We also need to determine in which guide to put it. It might be suitable for this guide, or we might decide that it's better suited to our internal guide. Personally, I'm happy to include it here but let's see what the group says.
@nmuller66 @sffrench
Happy for it to go here, I am subscribed to the other thread, and will keep an eye on the decision.
This guidance largely impacts our developer users more than most other writers in RH. However, because we refer our writers to the style guide, I think we could include a recommendation along with the other information about referring to object names. This guidance definitely belongs in Curriculum Guidelines. It may not be 100% enforceable, and there will certainly be exceptions, but that's true of nearly all our standards. It is appropriate to ask authors to be cognizant of the impact that their development choices have on the narrative that is presented to students.
I'll see if there are any other thoughts, then I'd like to create an issue for the guidelines site. We can present it as a recommendation.
We need to bump this up the list because it keeps happening and we usually don't find out until it's too late to do anything about it. The current course I'm editing has it everywhere.
Based on comments and discussion in https://github.com/RedHatTraining/skeleton/discussions/362 I'm going to take this on.
Updated info request: https://github.com/RedHatTraining/skeleton/discussions/362#discussioncomment-8913740
@daobrien Examples of this naming phenomenon:
From DO280:
Use the oc process --parameters command to view the parameter of the roster-template template.
From DO180:
In the previous example, a raw terminal is opened in the ruby-container container.
@daobrien I just came across an interesting naming example yesterday. It's not exactly aligned to the examples that you're looking for, but it might be an interesting edge case or point of discussion, so I'll share it anyway. (I'll also see if I can locate more typical examples.)
Example:
"Find the review5-path file. Save its absolute path in the /review5-disk/review5-path.txt file."
"Note the absolute path to the review5-path file from the preceding output."
In this case, the object name includes an object class that is not self-referential. In other words, the file includes "path" because the learner appends the file's path to another file. To me, this is confusing because the more common convention (which we are also trying to avoid) is that the object name and object class would be identical. When they are not identical, and part of the object name is also an object type, it's requires a little more cognitive load to map the object and its name correctly.
But, I do see the logic of naming a file with a keyword that relates to the learner's key task, or the contents of the file. So perhaps there's not an issue here after all.
Other steps in this activity name objects follow this same pattern of naming by using additional sets of criteria, such as: "Add the absolute path for the review5-perms file to the /review5-disk/review5-perms.txt file." But that's not as confusing because "perms" is not also an object type.
Re: https://github.com/RedHatTraining/skeleton/discussions/362#discussioncomment-10157641
The examples I have are the ones that have already been given. I do not have 2 different examples. Thank you for building up the guidelines @daobrien
@daobrien I just came across an interesting naming example yesterday. It's not exactly aligned to the examples that you're looking for, but it might be an interesting edge case or point of discussion, so I'll share it anyway. (I'll also see if I can locate more typical examples.)
Example: "Find the
review5-pathfile. Save its absolute path in the/review5-disk/review5-path.txtfile." "Note the absolute path to thereview5-pathfile from the preceding output."In this case, the object name includes an object class that is not self-referential. In other words, the file includes "path" because the learner appends the file's path to another file. To me, this is confusing because the more common convention (which we are also trying to avoid) is that the object name and object class would be identical. When they are not identical, and part of the object name is also an object type, it's requires a little more cognitive load to map the object and its name correctly.
But, I do see the logic of naming a file with a keyword that relates to the learner's key task, or the contents of the file. So perhaps there's not an issue here after all.
Other steps in this activity name objects follow this same pattern of naming by using additional sets of criteria, such as: "Add the absolute path for the
review5-permsfile to the/review5-disk/review5-perms.txtfile." But that's not as confusing because "perms" is not also an object type.
I'll be honest, I find this confusing. I'd love to get into the course where it appears and try to make sense of it. Without doing that I'd really only be guessing, but it seems like:
- There is a file named
review5-path(no extension) and you have to save the absolute path to that file in the/review5-disk/review5-path.txtfile. - Similarly for
review5-perms.
Naming is fun. NOT. :)
Another example of this phenomenon, from DO370:
"Verify that the famous-quotes-pvc PVC is successfully created."
Another example from DO370:
"Inspect the ocs-storagecluster-cephblockpool block pool and verify that it has three replicas."
Maybe you have enough examples for now?