Prepend internal members with _ to keep them private

[tvrprasad]

Per @Congelli501 at #518 (comment)
"You can prepend protected methods by an underscore.
This convention is widely used and static code checkers (at least eslint) can check that you only use _ methods with this."

This will help us control what's public API vs what's not.

[chdh]

Another solution would be to use TypeScript, which supports public/private/protected.

At the same time, API documentation in the source code should be introduced, e.g. JSDoc.

[tvrprasad]

Don't know much about TypeScript. How big an effort would it be to switch to TypeScript?

At the same time, API documentation in the source code should be introduced, e.g. JSDoc.

Sounds like where we want to be eventually with documentation.
@LuisBosquez FYI in case you feel inspired to look into this :-)

[chdh]

Don't know much about TypeScript. How big an effort would it be to switch to TypeScript?

TypeScript is a strict superset of ECMAScript 2015, so it should be possible to switch to TypeScript without having to modify any existing source code.

[arthurschreiber]

I'm okay with prepending _, or simply not documenting these features.

I'm not okay with moving to TypeScript. We've made this decision once (with CoffeeScript), and I'm not willing to do that mistake again. Yes, I know, there's a bunch of benefits of using TypeScript over plain JavaScript, but since ES2015/2016/2017 these are pretty marginal.

The only big one that is useful in my eyes is the type safety, but I've been thinking about using flow for this. Flow annotations are (as the name suggests) just a bunch of annotations, and don't introduce any new features or anything on top of standard JavaScript, so they are a lot more lightweight than switching to TypeScript.

[tvrprasad]

@arthurschreiber Static type checking sounds greatt! I assume you're referring to this - https://flowtype.org/

And what are your thoughts on JSDoc for API documentation?

[arthurschreiber]

@arthurschreiber Static type checking sounds greatt! I assume you're referring to this - https://flowtype.org/

Yup, that's right.

And what are your thoughts on JSDoc for API documentation?

I think that makes sense. I really don't like the current approach of having the documentation separate from the code. I think the JSDoc format is a good approach, the JSDoc tool itself is not that great. 😞

http://documentation.js.org/ does support JSDoc comments and even Flow annotations, IIRC.

[chdh]

I can't find an ESLint rule for private class members. There is a rule to disallow dangling underscores in identifiers, but that's not what we need.

There is an ESLint plugin for private variables, but it's not used frequently, it's version number is 0.1.2 and it hasn't been improved since June 2015.

It's not enough to have only the following two categories:

• Public class members, that are part of the public Tedious API.
• Private class members, that can only be called from within the same class.

There must be in-between categories like "protected", "package", "internal".

[Congelli501]

The rule no-underscore-dangle should work here. You can forbid the use of a leading underscore expect for this and super.

I have used flow with success for another project. It's incredibly fast to analyze the code (it's much faster than eslint static analysis for exemple).

[IanChokS]

So in the end we migrated over to TypeScript 😅 and used TypeDoc to document private and public methods