[docs] <Omit local variable types?>

[tillchen]

Is your feature request related to a problem? Please describe.
Thanks for providing the amazing new documentation!

While reading through the docs, I noticed that the usage of type annotations for local variables is not consistent.

For example, in the GitHub auth section: https://firebase.flutter.dev/docs/auth/social#github,

import 'package:github_sign_in/github_sign_in.dart';

Future<UserCredential> signInWithGitHub() async {
  // Create a GitHubSignIn instance
      final GitHubSignIn gitHubSignIn = GitHubSignIn(
          clientId: clientId,
          clientSecret: clientSecret,
          redirectUrl: 'https://my-project.firebaseapp.com/__/auth/handler');

  // Trigger the sign-in flow
  final result = await gitHubSignIn.signIn(context);

  // Create a credential from the access token
  final AuthCredential githubAuthCredential = GithubAuthProvider.credential(result.token);

  // Once signed in, return the UserCredential
  return await FirebaseAuth.instance.signInWithCredential(githubAuthCredential);
}

we omitted the type for result but not other variables.

But according to Effective Dart, we should AVOID type annotating initialized local variables: https://dart.dev/guides/language/effective-dart/design#avoid-type-annotating-initialized-local-variables. And there's also the linter rule "omit_local_variable_types": https://dart-lang.github.io/linter/lints/omit_local_variable_types.html.

Describe the solution you'd like
So should we modify the docs by removing all the type annotations for local variables?

Additional context

[helenaford]

Ah yes, that makes sense from reading that doc. Not sure however about the linter, could be quite restrictive, sometimes you may want to add a type for readability purposes.

[Ehesp]

The issue with not providing local types is that with documentation, it's sometimes tricky to read if you don't know the returned type.

[tillchen]

The issue with not providing local types is that with documentation, it's sometimes tricky to read if you don't know the returned type.

That's a good point. I just want to point out that for the official Firebase documentation, the Kotlin version also omits the types for the local variables. For example: https://firebase.google.com/docs/auth/android/google-signin#kotlin+ktx

private fun firebaseAuthWithGoogle(idToken: String) {
    val credential = GoogleAuthProvider.getCredential(idToken, null)
    auth.signInWithCredential(credential)
            .addOnCompleteListener(this) { task ->
                if (task.isSuccessful) {
                    // Sign in success, update UI with the signed-in user's information
                    Log.d(TAG, "signInWithCredential:success")
                    val user = auth.currentUser
                    updateUI(user)
                } else {
                    // If sign in fails, display a message to the user.
                    Log.w(TAG, "signInWithCredential:failure", task.exception)
                    // ...
                    Snackbar.make(view, "Authentication Failed.", Snackbar.LENGTH_SHORT).show()
                    updateUI(null)
                }

                // ...
            }
}

I think from my experience, I rarely care about the types for local variables. And omitting them makes the code more concise. Maybe we can keep the types for variables that are meant to be returned?

[tillchen]

So what should we do? If we don't want to remove the annotations, I'll just close this issue😄

[Salakar]

Personally I prefer them being visible on documentation as it makes its clearer what types are being used and helps if you wanted to lookup a certain type in the reference documentation.

But I agree the docs should be consistent in this case. We would love to see PRs for improving the documentation, theres an edit button at the bottom of every page that will take you were you need to go 🤓 and PRs are getting reviewed and merged fairly quickly now.