On Wednesday, January 03, 2018 06:10:10 Soulsbane via Digitalmars-d-learn wrote:
> I've only understood that imports should go in package.d. I'm seeing more and more packages on code.dlang.org using it for the packages primary code. Is this alright? As far as I can tell it's just bad form. It would be nice to have one of the maintainers higher up the food chain comment on this!
>
> Thanks!
The entire reason that the package.d feature was added was so that it would be possible to split a module into a package without breaking code. Anything beyond that was beyond the scope of the purpose of the feature, albeit not necessarily in conflict with its original purpose.
For better or worse, a number of folks like being able to just import an entire package at once using it, so it's not uncommon for folks to set it up to do that, though personally, I'm not a fan of that.
All Phobos has done with package.d thus far is split modules into packages, not add it for importing packages that already exist. As for leaving code in package.d, the only package in Phobos that I'm aware of doing that on a permanent basis is std.range, and I have no idea why that was done. When std.algorithm and std.container were split, package.d was used for documentation purposes (which makes a lot of sense), but there's no real code in there. std.datetime's package.d has some now-deprecated functionality that was left in there rather than being put in a module when std.datetime was split, because there was no point in putting it in a module. In the long run though, all of that will be gone from std.datetime's package.d, and it too will only be used for documentation. I have no idea what folks have been doing on code.dlang.org.
In terms of functionality, there really isn't much special about package.d. If there were, we probably wouldn't have been able to talk Walter into it. We were able to precisely because public imports already worked in a way that allowed package.d to work. We just needed the feature to be added to make it possible to import a package. So, package.d allows that, but beyond that, it's just a normal module. It typically containts public imports for the rest of the package, but it doesn't have to, and it can contain whatever code you want to put in there. You can do whatever you want with it, though really, using it for much of anything at all beyond splitting up a package in place is beyond the scope of why it was introduced. But ultimately, there's nothing really special about package.d, and different folks have different ideas about it and how it should be used.
Personally, I don't think that it's very clean to be putting stuff other than documentation in package.d, and I don't really like the idea of setting it up to import the entire package under normal circumstances; I see it simply as a way to split up a module in place without breaking code, but that's just how I feel about it. I don't know that there are much in the way of objective arguments about package.d and how it should be used.
However, at this point, the trend in best practices is towards using scoped, selective imports as much as possible (since that reduces compilation times and more closely associates the imports with what's using them), and that pretty much flies in the face of the idea of importing an entire package at once. You _can_ use selective imports and package.d together, but it also makes the compiler do more work than if you just selectively imported from the module that the symbol is actually in. And if you're putting code directly in package.d, then it's not possible to import just that module unless it doesn't have any public imports in it. So, from a flexibility standpoint, it makes more sense to avoid putting symbols directly in package.d.
However, AFAIK, there really isn't much in the way of best practices with regards to package.d. All Phobos has done with it has been to split modules into packages like it was originally intended, and beyond that, folks have kind of done whatever they want. You may find a bunch of people agreeing with you that folks shouldn't be putting normal code in package.d, but AFAIK, there's no real general agreement on the matter one way or the other. There isn't really even agreement about whether package.d should be used when it isn't needed (and it's pretty much only needed when splitting up a module in-place).
- Jonathan M Davis
| 
Permalink
Reply
