I've perused both the spec[1] and Andrei's book, and I the idea I get is that module declarations are optional, recommended only in case of file names not being valid D names. But in the community (and Phobos) I see it's strongly recommended and used throughout.

What's the reason? If the declaration overrides the path (provided the file is found) rather than enforcing path consistency by outputting a compile error, then what's the benefit of module declarations, if we have to be disciplined to keep it consistent with paths anyway?

I'm busy starting my first big multi file D project, thanks for any feedback!


[1] https://dlang.org/spec/module.html#ModuleDeclaration

On Sunday, 26 March 2017 at 20:51:01 UTC, XavierAP wrote:
> I've perused both the spec[1] and Andrei's book, and I the idea I get is that module declarations are optional, recommended only in case of file names not being valid D names.

Module declarations are only optional in the most trivial case that is rarely useful in real world code. I recommend you ALWAYS use them (and always put a ddoc comment on them!), and moreover that you avoid top name modules (use `myproject.modname` instead of `modname`) to avoid conflicts.

If you don't, you are depending on implicit magic and just hoping that there's no conflict from third party libraries, and those lead to problems, almost guaranteed before long.

> if we have to be disciplined to keep it consistent with paths anyway?

That's false, the path is irrelevant to the D language, ONLY the module declaration gives the canonical name. The path is just a helper for automatic tools to find the module given an import, but my preference is to ditch those things and actually just list your modules by name anyway. Then everything works reliably and consistently.

On Sunday, 26 March 2017 at 20:58:24 UTC, Adam D. Ruppe wrote:
>
> Module declarations are only optional in the most trivial case that is rarely useful in real world code. I recommend you ALWAYS use them (and always put a ddoc comment on them!), and moreover that you avoid top name modules (use `myproject.modname` instead of `modname`) to avoid conflicts.

OK I was already doing it all this in the multi-file project. I was curious but I guess it's long to explain the different things that can go wrong if one doesn't declare module names.

Followup question: if I am inside module myproj.pack1.mod1 and want to import myproj.pack1.mod2... should I import myproj.pack1.mod2; or import mod2; ?

On Sunday, 26 March 2017 at 22:10:07 UTC, XavierAP wrote:
> I was curious but I guess it's long to explain the different things that can go wrong if one doesn't declare module names.

You'll just get a name conflict eventually. Either two modules with the same name, or "module `foo` must be imported as `foo.bar`" errors when stuff fails to line up, then you'll need to go in and change all the imports to fix it. Real hassle to do later, real easy to do now.

> Followup question: if I am inside module myproj.pack1.mod1 and want to import myproj.pack1.mod2... should I import myproj.pack1.mod2; or import mod2; ?

Always use the full module name in import. If you want to abbreviate it, do

module something = myproj.pack.mod2;

then you can refer to it as `something` throughout the usage points in that file.

On Sunday, 26 March 2017 at 20:51:01 UTC, XavierAP wrote:
> I've perused both the spec[1] and Andrei's book, and I the idea I get is that module declarations are optional, recommended only in case of file names not being valid D names. But in the community (and Phobos) I see it's strongly recommended and used throughout.
>
> What's the reason? If the declaration overrides the path (provided the file is found) rather than enforcing path consistency by outputting a compile error, then what's the benefit of module declarations, if we have to be disciplined to keep it consistent with paths anyway?
>
> I'm busy starting my first big multi file D project, thanks for any feedback!
>
>
> [1] https://dlang.org/spec/module.html#ModuleDeclaration

In addition to what Adam has said, they allow you to treat the module as a symbol during compilation. You _can_ do that with the implicitly generated one, but you can't do things that requires the declared symbol, e.g. attach UDAs which is how dcompute distinguishes device modules from host modules and possibly reflect of the symbols (although you can use __MODULE__ for that).

On Sunday, March 26, 2017 20:51:01 XavierAP via Digitalmars-d-learn wrote:
> I've perused both the spec[1] and Andrei's book, and I the idea I get is that module declarations are optional, recommended only in case of file names not being valid D names. But in the community (and Phobos) I see it's strongly recommended and used throughout.
>
> What's the reason? If the declaration overrides the path (provided the file is found) rather than enforcing path consistency by outputting a compile error, then what's the benefit of module declarations, if we have to be disciplined to keep it consistent with paths anyway?
>
> I'm busy starting my first big multi file D project, thanks for any feedback!
>
>
> [1] https://dlang.org/spec/module.html#ModuleDeclaration

What it really comes down to is that if you don't give the module name, the compiler infers it, and it doesn't infer packages. So, if you have

foo/bar.d

where bar.d's contents are

==========================================
void main()
{
    pragma(msg, __MODULE__);
}
==========================================

and you compile with dmd foo/bar.d, you're going to see

bar

printed, whereas if you have

==========================================
module foo.bar

void main()
{
    pragma(msg, __MODULE__);
}
==========================================

then you'll see

foo.bar

printed. So, if all you're ever doing is one file programs, then it really doesn't matter, but if you're doing anything with packages, you have to use module declarations. You also have to use them if you want to document a module.

As for "overiding" the path... the compiler and other tools use the module path as the path on disk to look for the files - e.g. if you tell the compiler that /usr/local/include/dlang/ is an import directory, it'll start looking for modules in there, and if it's looking for foo.bar, that means that it's looking for /usr/local/include/dlang/foo/bar.d. On some level, it is possible to give a module name or package name that doesn't match the exact file or folder names on disk, but really, that's just asking for trouble. It'll work in some basic cases, but it'll fall flat on its face in real projects.

rdmd goes a step further and will compile additional modules based on what's imported (i.e. if a module is imported but wasn't previously compiled, it'll compile it), and when a tool does something like that, it makes it that much worse if your module path isn't equivalent to the path on disk.

- Jonathan M Davis