Clarify calling one library in two ways on 'Effective Dart: Usage' page

[dark-chocolate]

Page URL: https://dart.dev/guides/language/effective-dart/usage
Page source: https://github.com/dart-lang/site-www/tree/master/src/_guides/language/effective-dart/usage.md

Description of issue:

Quoting this article,

I think the first line is not bad, but actually is the right way to import. It is further confirmed in the next section:

[kwalrath]

It's true that the first line isn't bad; it's the combination of the two lines that's bad. I'm not sure how to make this clearer.

[dark-chocolate]

@kwalrath By "combination", do you mean there should be a space between the two lines (as mentioned in best practices)?

[kwalrath]

No, I mean that you're including the same library in two different ways, which is very bad.

Maybe we could change the example to something like this:

// This import by itself would be fine.
import 'package:my_package/api.dart';

// This import causes problems because it imports the same file (api.dart)
// but uses a different path. Avoiding ../lib imports prevents this problem. 
import '../lib/api.dart'; // Reaching into lib.

[kwalrath]

/cc @munificent in case he has suggestions.

[dark-chocolate]

@kwalrath I didn't pay attention to the 2nd import line in 1st screenshot. I thought it would be import 'test_utils.dart'. I got your point now.

[kwalrath]

@kwalrath I didn't pay attention to the 2nd import line in 1st screenshot. I thought it would be import 'test_utils.dart'. I got your point now.

You aren't the first person to be confused by the example, so I think it needs some improvement.

[kwalrath]

Turns out we had a PR from long ago that aims to fix this. I think it's ready to commit, and I hope it helps.

[parlough]

I think the addition of a "good" example with the current text after #3066 seems to sufficiently solve this issue. Let me know if you think further additions or changes are needed.

Thanks again for creating an issue for this!

[dark-chocolate]

Hi,

It's still confusing to have first import line (which is good) in the bad section.

I think it will make more sense if we can write it like this:

api.dart can be imported in two ways:

1. import '../lib/api.dart'; (bad)
2. import 'package:my_package/api.dart'; (good)

[parlough]

Hi @dark-chocolate, thanks for raising the concern. Taking a look, this snippet is not about the first one being good and the second one being bad, it's about how importing in both ways at the same time is very confusing and causes issues. So the suggestion to this issue, is to just stick to the package one.

If we only put the import '../lib/api.dart'; in the bad section, it doesn't illustrate the potential ("bad") issues that may arise.

Keeping that in mind, do you see someway this would be more clear?

[dark-chocolate]

@parlough

It's not clear what is bad.

import '../lib/api.dart';

or the combination of

import 'package:my_package/api.dart';
import '../lib/api.dart';

Of course both are bad. I think the docs needs to convey the following message explicitly because the reader also knows that importing both will be bad, the doc was (I think) more about what should be the correct way of importing.

it's about how importing in both ways at the same time is very confusing and causes issues