Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Future] Move away from documenting "null safety" as its own entity #4603

Open
6 tasks
parlough opened this issue Feb 17, 2023 · 2 comments
Open
6 tasks

[Future] Move away from documenting "null safety" as its own entity #4603

parlough opened this issue Feb 17, 2023 · 2 comments
Labels
dev.null-safety Relates to transforming or migrating Dart code to sound null safety dev.type-system Relates to the type system in Dart e4-months Can complete in >= 1 month of normal, not dedicated, work from.team Reported by Dash docs team member p3-low Valid but not urgent concern. Resolve when possible. Encourage upvote to surface. st.blocked Issue cannot continue until another action completes st.triage.ltw Indicates Lead Tech Writer has triaged

Comments

@parlough
Copy link
Member

parlough commented Feb 17, 2023

Currently we have a lot of documentation covering null safety as both an integrated and an isolated concept, but it really is just a part of the type system. In the longer term (far post Dart 3) "null safety" as a term likely shouldn't be super common on the site, but instead be incorporated naturally across the entire documentation, particularly updated type and type systems sections.

Prerequisites:

Some steps:

  • Consider a new nullable type section or subsection to new language docs
  • Verify nullable and non-nullable types are covered and used as necessary across all docs on the site
  • Introduce specific or better examples in cheatsheets and/or codelabs around nullable types
  • Update or rewrite type system article to be more thorough in nullable and non-nullable types (Understanding null safety has great related content)

Way later steps:

  • Remove all mentions of unsound null safety (--no-sound-null-safety)
  • Remove or archive articles about enabling and configuring null safety
@parlough parlough added p3-low Valid but not urgent concern. Resolve when possible. Encourage upvote to surface. st.blocked Issue cannot continue until another action completes e4-months Can complete in >= 1 month of normal, not dedicated, work dev.null-safety Relates to transforming or migrating Dart code to sound null safety labels Feb 17, 2023
@parlough parlough mentioned this issue Feb 22, 2023
7 tasks
@atsansone atsansone added this to the Next Major Release milestone Apr 4, 2023
@atsansone atsansone added st.triage.ltw Indicates Lead Tech Writer has triaged dev.type-system Relates to the type system in Dart labels Apr 29, 2023
@MaryaBelanger
Copy link
Contributor

Small subset of this, but there's been conversation about ?. and getting the useful info from https://dart.dev/null-safety/understanding-null-safety#smarter-null-aware-methods into the "core docs", specifically the operators page where ?. is "discussed" (there's like, a sentence about it at the bottom of the page).

From @fishythefish :

Do we have a good reference page for what ?. does? I've found https://dart.dev/language/operators#other-operators and https://dart.dev/language/classes#using-class-members, but I'm wondering if there are any others. I've noticed two common misunderstandings of this operator in google3:

  1. Some code uses ?. for every property access. I can sort of see the reasoning prior to null safety, but many of these uses flow into code that's going to blow up on null anyway. It feels like users think ?. magically avoids NPEs altogether.
  2. A lot of code (and some reviewers) assume that once you have ?. somewhere in a property chain, you need ?. on every subsequent access in the chain. This one's understandable - if you don't know about the short-circuiting behavior, it's reasonable to read foo?.bar.baz as (foo?.bar).baz and then "correct" it to foo?.bar?.baz. I didn't find any documentation of this behavior, even in the spec.

And also links to this: https://github.com/dart-lang/language/blob/main/accepted/2.12/nnbd/feature-specification.md#null-aware-operator

Maybe this should be handled in a break out issue, just documenting here since it's part of the null safety break down.

@fishythefish
Copy link
Member

A clarification from @srawlins in response to point 2:

That's also reasonable because there was no null-shortening before null safety.

I didn't realize this was something added in null safety until I went back and looked at the feature specification again. Analyzer does emit a diagnostic for unnecessary uses of ?. so it's fairly easy to clean up those uses, but I've had a few code reviewers confused by this change in boilerplate.

@atsansone atsansone added the from.team Reported by Dash docs team member label Aug 8, 2023
parlough added a commit that referenced this issue Feb 14, 2024
Removes the null safety codelab and references to it. In a few days, I
will follow up soon with some new samples on the cheatsheet to replace
this.

This codelab is the least viewed on the site and no longer makes sense
to separate from other language learning. As mentioned, I will follow up
with a few new samples on the cheatsheet as a stop-gap until we
implement a consolidated new-learner experience.

Contributes to #5382
Contributes to #4603
Closes #3093
atsansone pushed a commit to atsansone/site-www that referenced this issue Feb 20, 2024
Removes the null safety codelab and references to it. In a few days, I
will follow up soon with some new samples on the cheatsheet to replace
this.

This codelab is the least viewed on the site and no longer makes sense
to separate from other language learning. As mentioned, I will follow up
with a few new samples on the cheatsheet as a stop-gap until we
implement a consolidated new-learner experience.

Contributes to dart-lang#5382
Contributes to dart-lang#4603
Closes dart-lang#3093
atsansone pushed a commit to atsansone/site-www that referenced this issue Mar 22, 2024
Removes the null safety codelab and references to it. In a few days, I
will follow up soon with some new samples on the cheatsheet to replace
this.

This codelab is the least viewed on the site and no longer makes sense
to separate from other language learning. As mentioned, I will follow up
with a few new samples on the cheatsheet as a stop-gap until we
implement a consolidated new-learner experience.

Contributes to dart-lang#5382
Contributes to dart-lang#4603
Closes dart-lang#3093
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dev.null-safety Relates to transforming or migrating Dart code to sound null safety dev.type-system Relates to the type system in Dart e4-months Can complete in >= 1 month of normal, not dedicated, work from.team Reported by Dash docs team member p3-low Valid but not urgent concern. Resolve when possible. Encourage upvote to surface. st.blocked Issue cannot continue until another action completes st.triage.ltw Indicates Lead Tech Writer has triaged
Projects
None yet
Development

No branches or pull requests

4 participants