#35347 closed Cleanup/optimization (fixed)
Clarify choice_set attribute in tutorial 2
Reported by: | Lang Tran | Owned by: | Lang Tran |
---|---|---|---|
Component: | Documentation | Version: | 5.0 |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Ready for checkin | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | yes | UI/UX: | no |
Description
[Tutorial 2](https://docs.djangoproject.com/en/5.0/intro/tutorial02/) introduces usage of the function choice_set
, generated from the foreign key to Question in the Choice object. However, the tutorial does not specify where this function comes from or why it is created.
Adding a short blurb in the comments of the code block will clarify this and explain how choice_set
is created.
Change History (12)
comment:1 by , 7 months ago
Has patch: | set |
---|
comment:2 by , 7 months ago
Resolution: | → worksforme |
---|---|
Status: | assigned → closed |
comment:3 by , 7 months ago
Going through the tutorial as a relative newcomer to Django I had trouble investigating on my own how and where choice_set
came from- now that you point out the prior paragraph in detail, that makes sense, but I think it would at least be helpful if we were to explicitly mention choice_set
even in that paragraph as a method created from the related object set. I have personally found that when it comes to these autogenerated methods based on some existing member the convention around what they're called, how they're named, etc can be a bit murky unless explicitly called out.
comment:4 by , 7 months ago
Resolution: | worksforme |
---|---|
Status: | closed → new |
Triage Stage: | Unreviewed → Accepted |
Thank you Lang for your response. I can see how by not mentioning choice_set
, we are adding an extra interpretation burden to the reader.
I'm happy to review a PR that adds that clarification, would you like to re-purpose your previous PR? I'll re-open the ticket and the GitHub PR.
comment:5 by , 7 months ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
comment:6 by , 7 months ago
Patch needs improvement: | set |
---|
follow-up: 8 comment:7 by , 7 months ago
I doubt it's a common source of confusion. "Django creates a set... which can be accessed via the API." does all but name the set. We could say something like, "Django creates a choice_set attribute on Question instances..." but it feels a bit unnecessary when example usage follows two lines later.
comment:8 by , 7 months ago
Replying to Tim Graham:
I doubt it's a common source of confusion. "Django creates a set... which can be accessed via the API." does all but name the set. We could say something like, "Django creates a choice_set attribute on Question instances..." but it feels a bit unnecessary when example usage follows two lines later.
My understanding from the original report is that for someone new to Django, it's not easy to make the connection that "the set" is actually named choice_set
. I know both things have the word "set" in it, but I fear we may be too involved already in the project to not see the connection (but newcomers may easily miss it).
I remember when I was learning Django, and seeing references to the magical something_set
attribute, and given my lack of experience and the inevitable language barrier, I assume it to be a "weirdly named thing that was like that just because a core dev did not like plurals" and not because _set
actually meant "the set of [related] somethings". More so, when you read the tutorial in another language, "set" could be translated to the proper term in that language so the connection is quite challenging to be made, or worse, is not translated at all (because it's a code comment) and the explanation is totally missed if the reader does not understand English!
comment:9 by , 7 months ago
That was pretty much my experience going through the tutorial. The link between choice_set
and "the set" wasn't explicit enough for me to make the connection, particularly when you're skimming comments as people typically do. Another benefit is that if we explicitly mention it within the comment then if somebody is ctrl+f-ing through the docs then they'll see it mentioned in the comment and be able to make the connection.
comment:10 by , 7 months ago
Patch needs improvement: | unset |
---|---|
Summary: | Clarify choice_set function in tutorial 2 → Clarify choice_set attribute in tutorial 2 |
Triage Stage: | Accepted → Ready for checkin |
The clarification is already present in the docs:
which says almost the same of what's proposed in the PR, but it's in the same paragraph where the next steps are explained as a meaningful unit. I'm not sure this should be changed, would you have more details on why the above may not be sufficient?