Namespaces / Modules - the preferred way

[tihomir-kit]

Hi all,

I'm not sure if this is a small typo/mistake or if I'm not getting it right. On the Namespaces and Modules page there seems to be 2 preferred ways of architecting the code.

The top of the document says:

A note about terminology: It’s important to note that in TypeScript 1.5, the nomenclature has changed. “Internal modules” are now “namespaces”. “External modules” are now simply “modules”, as to align with ECMAScript 2015’s terminology, (namely that module X { is equivalent to the now-preferred namespace X {).

Then later under the "Modules" sections the documents says the opposite:

Starting with ECMAScript 2015, modules are native part of the language, and should be supported by all compliant engine implementations. Thus, for new projects modules would be the recommended code organization mechanism.

So my guess is that the mistake is probably in the heading.

[DanielRosenwasser]

I should clarify - if you're using namespaces, it's preferred to use the namespace keyword. But you shouldn't be using namespaces, you should be using modules because that's the way going forward.

[hoegge]

I agree, that the current description is not very easy to comprehend for a new person learning typescript, especially since the documentation at typescriptlang.org is limited and people need to search other resources on the internet, that are not necessarily up to date or correct.

A few things could be done to improve understanding:

• State that internal modules ARE what was previously written like:

module NiceModuleName {
    export function Funktion() {
        ...
    }
}

• and that the module statement should not be use anymore this way and that internal modules now is called namespaces and that there is no difference between those deprecated (internal) modules and namespaces:

namespace NiceModuleName {
    export function Funktion() {
        ...
    }
}

• The use of module this way should be planned for deprecation at some point even if it requires ECMA updates - or at least a TSLINT should detect it and tell the user to use namespace
• Clarify that the above use of module is not creating a module but a namespace
• Only use the word module when talking about external modules

If you are very clear about this yourself, the current documentation seems clear about that. But if you don't know this - then the current documentation does not really help people understand this fact.

PS: Maybe I have still not understood it - which then supports my point ;-)

[gschjetne]

@DanielRosenwasser

But you shouldn't be using namespaces, you should be using modules because that's the way going forward.

What does that mean? That namespaces are deprecated, or they will be deprecated soon?

That would be a shame, enforcing a 1-to-1 relationship between modules and files is highly restrictive.

[tparikka]

Another beginner here trying to learn TS, I also found that line about preferring namespace to be confusing.

[hoegge]

@tparikka
It just means, that you should not use the word "module" but the word "namespace" insetad (which means the same) but is not at the risk of being confused with the moden JS/TS (external) modules