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

doc: import aliasing clarification #34603

Open
shousper opened this issue Sep 30, 2019 · 3 comments
Open

doc: import aliasing clarification #34603

shousper opened this issue Sep 30, 2019 · 3 comments
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@shousper
Copy link

Looking at the documentation about dealing with import collisions, the code review comments document says:

In the event of collision, prefer to rename the most local or project-specific import.

Indicating that the packages in the local repository should be aliased, rather than external packages.

Meanwhile, the Effective Go section on package names says:

..in the rare case of a collision the importing package can choose a different name to use locally.

Which reads to me in opposition to the code review comments recommendation; suggesting the imported (external) package should be aliased, not the local package of the same name.

I tried to find some more information about a "why" for either of these recommendations in the issues and PRs here, but came up empty..

Could I be so bold as to request some further clarification of the recommendation?

Thanks in advance!

@bcmills
Copy link
Contributor

bcmills commented Sep 30, 2019

You should prefer not to rename the less-project-specific import because, all else equal, another reader of the code is more likely to me familiar with that package, and thus more likely to understand the original name without further context.

The word “locally” in Effective Go is referring to the name that is used “locally” within the importing source file, not the locality of the package being imported. (It's telling you that some package can be renamed, not indicating which one should be renamed.)

@bcmills bcmills added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Sep 30, 2019
@bcmills bcmills added this to the Unreleased milestone Sep 30, 2019
@shousper
Copy link
Author

shousper commented Oct 8, 2019

Thanks @bcmills, that makes sense. Appreciate the quick & concise explanation!

Now that you've mentioned:

another reader of the code is more likely to me familiar with that package

It is clearer that it is more so talking about third-party/open-source packages that might be well known. We were looking at imports of our own (private) packages and felt that the opposite made more sense to us when names collide.

For example, we might have 2 packages x.sh/services/user and x.sh/routers/user where the later imports the former. We would typically alias the non-local package in this instance if for no other reason than the majority of code would mostly use the local package and only a few lines would use the non-local one.

Would you say this still a bad idea and the local package should actually be the aliased one?

@bcmills
Copy link
Contributor

bcmills commented Oct 11, 2019

Would you say this still a bad idea and the local package should actually be the aliased one?

I would say that if one of the colliding packages is closed-source and under your control, you should change the package name instead of renaming it during import.

See https://blog.golang.org/package-names (especially the “Avoid unnecessary package name collisions” part).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

3 participants