8 ms·

Seems like a dumb question, but I find that even BLATANTLY_OBVIOUS_WARNINGS are so much more effective if there is a 'why' that explains the danger.

quietbritishjim 5y ago
Here it seems "INTERNALS" is the "why". If it's not a public API then of course it could change or disappear without warning between releases (including minor releases).
- verdverm 5y ago
  Go handles this by not allowing 3rd party to import a package path with internal/ in it. Only the current module can
  - MaulingMonkey 5y ago
    Ancient vanilla JS can accomplish similar by using wrapper functions. var React = (function(){ var React = {}; var __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED = {}; ...code extending/using React etc... return React; })(); // accessible: React.whatever // inaccessible: __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED However, there's always caveats where language level access controls don't let you quite express the access restriction you want. Perhaps you want to expose something to other official modules from the same constillation of libraries, for example (meaning you wouldn't be able to use Go's "internal"), without comitting to supporting the semver contract for any other arbitrary user of your API (meaning you might resort to similarly scary names.)
    - ______-_-______ 5y ago
      iirc, react-dom (a separate package) needs to access that property as well, which is why it's exposed in the first place
    - udbhavs 5y ago
      Private properties in JS classes are syntactic sugar that compile to variable definitions like this in the object's scope
  - mdoms 5y ago
    Most sane languages have visibility modifiers. This link refers to Javascript so...
    - verdverm 5y ago
      Go did that with casing, so you can tell visibility without lookup or needing to think. The internal/ is a package level restriction, so somewhat orthogonal in that they are for different levels
  - drdaeman 5y ago
    Which is awful, because I've seen a number of FLOSS projects that have perfectly good reusable code in their internal/ subdirectories. And I mean code by no means unique or specific to those projects. And whoever says something about instability or APIs being subject to change without notice - they're wrong because those are Go git repos and one can always pin to an old tag or even a commit SHA. If something is unusable (too specific, too fragile, too flaky), no one would use that anyway. A warning is fine and even welcomed, but a block is a slap in the face.
deleted 5y ago
[deleted]
marcosdumay 5y ago
It's certainly not dumb. If you look at every large library, there are some forbidden internal symbols that are used in a lot of 3rd part projects. Many times those are more stable than the API, and often enough they get published as part of the API once a lot of people decide to depend on them.
- wk_end 5y ago
  It's maybe not dumb to use the forbidden internal symbols, but it's certainly dumb to go ask the folks who through naming and documentation have communicated almost comically loudly and explicitly that they don't want you using the symbols if it's cool if you use the symbols.
  - marcosdumay 5y ago
    You would be surprised about how many times I've seen the internalVariableDoNotUse symbol to be exposed on the formal API of a library because everybody uses it already, it would be too much work to change it.
dmd 5y ago
One of my favorites is the warning you get if you enter the shell of an Oracle ZFS storage appliance: +-----------------------------------------------------------------------------+ | You are entering the operating system shell. By confirming this action in | | the appliance shell you have agreed that THIS ACTION MAY VOID ANY SUPPORT | | AGREEMENT. If you do not agree to this -- or do not otherwise understand | | what you are doing -- you should type "exit" at the shell prompt. EVERY | | COMMAND THAT YOU EXECUTE HERE IS AUDITED, and support personnel may use | | this audit trail to substantiate invalidating your support contract. The | | operating system shell is NOT a supported mechanism for managing this | | appliance, and COMMANDS EXECUTED HERE MAY DO IRREPARABLE HARM. | | | | NOTHING SHOULD BE ATTEMPTED HERE BY UNTRAINED SUPPORT PERSONNEL UNDER ANY | | CIRCUMSTANCES. This appliance is a non-traditional operating system | | environment, and expertise in a traditional operating system environment | | in NO WAY constitutes training for supporting this appliance. THOSE WITH | | EXPERTISE IN OTHER SYSTEMS -- HOWEVER SUPERFICIALLY SIMILAR -- ARE MORE | | LIKELY TO MISTAKENLY EXECUTE OPERATIONS HERE THAT WILL DO IRREPARABLE | | HARM. Unless you have been explicitly trained on supporting this | | appliance via the operating system shell, you should immediately return | | to the appliance shell. | | | | Type "exit" now to return to the appliance shell. | +-----------------------------------------------------------------------------+ I like how it explicitly says "no, seriously, Mister Unix Wizard, we mean YOU."
- duxup 5y ago
  >"no, seriously, Mister Unix Wizard, we mean YOU." That makes sense as they're the folks who will get in trouble. Rando person probably turns back at this point "nope this isn't what I wanted". Guy who thinks he knows better is the one who keeps going and freaks out when it hits the fan.
- Gaelan 5y ago
  +-----------------------------------------------------------------------------+ | You are entering the operating system shell. By confirming this action in | | the appliance shell you have agreed that THIS ACTION MAY VOID ANY SUPPORT | | AGREEMENT. If you do not agree to this -- or do not otherwise understand | | what you are doing -- you should type "exit" at the shell prompt. EVERY | | COMMAND THAT YOU EXECUTE HERE IS AUDITED, and support personnel may use | | this audit trail to substantiate invalidating your support contract. The | | operating system shell is NOT a supported mechanism for managing this | | appliance, and COMMANDS EXECUTED HERE MAY DO IRREPARABLE HARM. | | | | NOTHING SHOULD BE ATTEMPTED HERE BY UNTRAINED SUPPORT PERSONNEL UNDER ANY | | CIRCUMSTANCES. This appliance is a non-traditional operating system | | environment, and expertise in a traditional operating system environment | | in NO WAY constitutes training for supporting this appliance. THOSE WITH | | EXPERTISE IN OTHER SYSTEMS -- HOWEVER SUPERFICIALLY SIMILAR -- ARE MORE | | LIKELY TO MISTAKENLY EXECUTE OPERATIONS HERE THAT WILL DO IRREPARABLE | | HARM. Unless you have been explicitly trained on supporting this | | appliance via the operating system shell, you should immediately return | | to the appliance shell. | | | | Type "exit" now to return to the appliance shell. | +-----------------------------------------------------------------------------+ Cleaned up formatting
dahfizz 5y ago
It depends. If you give a reason why, it opens up the door for people to argue about whether the "why" is a valid justification. It also can make people feel like the "why" does not apply to them.
- MaulingMonkey 5y ago
  "why" can be pretty nebulous too. For a larger, widely used project, the question isn't "why" make something internal, but "why not". The safe default is to not semi-permanently commit every half baked bit of code to the public stable semvered API boundary to support for who knows how many years, but to only do so after careful consideration and justification. To add this disclaimer to every single bit of internal code is to drown your codebase in a sea of redundant comments - none of which are specific to the code, or even the codebase, but are instead rehashing "why encapsulation?" 101. This will only train readers of your code to ignore the low-value low-signal comments, and they will then end up asking the same question anyways, and "read the comment that's right there!!!111oneoneone" will be a fustrating experience for everyone, although they might not be able to articulate why. The real question I'm curious about here isn't "why are internal things internal" - but why this internal thing must technically be public. Does this predate ES6 symbols? Is there a plan to switch to those at some point in the future? Is there a tracking issue? Or does this need to be accessed from elsewhere in a manner that makes Symbols awkward to use? Where?
deleted 5y ago
[deleted]
Imnimo 5y ago
The "why" is that you will be fired, clearly :P
- Grollicus 5y ago
  I suspect they'll soon have an issue where someone wanted to get fired but it didn't work...
  - MaxBarraclough 5y ago
    Interesting point. In naming it this way, the maintainers have committed to firing anyone who uses it, as an implicit guarantee of the public-facing API. Fortunately they're free to rename it in their next release. Perhaps something snappy like __secret_internals_do_not_use_or_version_specific_retribution_will_follow_possibly_including_firing
cbhl 5y ago
I wouldn't be surprised if there is a FB-internal comment (or commit message) that was stripped in the open source repos

quietbritishjim 5y ago

Here it seems "INTERNALS" is the "why". If it's not a public API then of course it could change or disappear without warning between releases (including minor releases).

verdverm 5y ago
Go handles this by not allowing 3rd party to import a package path with internal/ in it. Only the current module can
- MaulingMonkey 5y ago
  Ancient vanilla JS can accomplish similar by using wrapper functions. var React = (function(){ var React = {}; var __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED = {}; ...code extending/using React etc... return React; })(); // accessible: React.whatever // inaccessible: __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED However, there's always caveats where language level access controls don't let you quite express the access restriction you want. Perhaps you want to expose something to other official modules from the same constillation of libraries, for example (meaning you wouldn't be able to use Go's "internal"), without comitting to supporting the semver contract for any other arbitrary user of your API (meaning you might resort to similarly scary names.)
  - ______-_-______ 5y ago
    iirc, react-dom (a separate package) needs to access that property as well, which is why it's exposed in the first place
  - udbhavs 5y ago
    Private properties in JS classes are syntactic sugar that compile to variable definitions like this in the object's scope
- mdoms 5y ago
  Most sane languages have visibility modifiers. This link refers to Javascript so...
  - verdverm 5y ago
    Go did that with casing, so you can tell visibility without lookup or needing to think. The internal/ is a package level restriction, so somewhat orthogonal in that they are for different levels
- drdaeman 5y ago
  Which is awful, because I've seen a number of FLOSS projects that have perfectly good reusable code in their internal/ subdirectories. And I mean code by no means unique or specific to those projects. And whoever says something about instability or APIs being subject to change without notice - they're wrong because those are Go git repos and one can always pin to an old tag or even a commit SHA. If something is unusable (too specific, too fragile, too flaky), no one would use that anyway. A warning is fine and even welcomed, but a block is a slap in the face.

deleted 5y ago

[deleted]

marcosdumay 5y ago

It's certainly not dumb. If you look at every large library, there are some forbidden internal symbols that are used in a lot of 3rd part projects. Many times those are more stable than the API, and often enough they get published as part of the API once a lot of people decide to depend on them.

wk_end 5y ago
It's maybe not dumb to use the forbidden internal symbols, but it's certainly dumb to go ask the folks who through naming and documentation have communicated almost comically loudly and explicitly that they don't want you using the symbols if it's cool if you use the symbols.
- marcosdumay 5y ago
  You would be surprised about how many times I've seen the internalVariableDoNotUse symbol to be exposed on the formal API of a library because everybody uses it already, it would be too much work to change it.

dmd 5y ago

One of my favorites is the warning you get if you enter the shell of an Oracle ZFS storage appliance: +-----------------------------------------------------------------------------+ | You are entering the operating system shell. By confirming this action in | | the appliance shell you have agreed that THIS ACTION MAY VOID ANY SUPPORT | | AGREEMENT. If you do not agree to this -- or do not otherwise understand | | what you are doing -- you should type "exit" at the shell prompt. EVERY | | COMMAND THAT YOU EXECUTE HERE IS AUDITED, and support personnel may use | | this audit trail to substantiate invalidating your support contract. The | | operating system shell is NOT a supported mechanism for managing this | | appliance, and COMMANDS EXECUTED HERE MAY DO IRREPARABLE HARM. | | | | NOTHING SHOULD BE ATTEMPTED HERE BY UNTRAINED SUPPORT PERSONNEL UNDER ANY | | CIRCUMSTANCES. This appliance is a non-traditional operating system | | environment, and expertise in a traditional operating system environment | | in NO WAY constitutes training for supporting this appliance. THOSE WITH | | EXPERTISE IN OTHER SYSTEMS -- HOWEVER SUPERFICIALLY SIMILAR -- ARE MORE | | LIKELY TO MISTAKENLY EXECUTE OPERATIONS HERE THAT WILL DO IRREPARABLE | | HARM. Unless you have been explicitly trained on supporting this | | appliance via the operating system shell, you should immediately return | | to the appliance shell. | | | | Type "exit" now to return to the appliance shell. | +-----------------------------------------------------------------------------+ I like how it explicitly says "no, seriously, Mister Unix Wizard, we mean YOU."

duxup 5y ago
>"no, seriously, Mister Unix Wizard, we mean YOU." That makes sense as they're the folks who will get in trouble. Rando person probably turns back at this point "nope this isn't what I wanted". Guy who thinks he knows better is the one who keeps going and freaks out when it hits the fan.
Gaelan 5y ago
+-----------------------------------------------------------------------------+ | You are entering the operating system shell. By confirming this action in | | the appliance shell you have agreed that THIS ACTION MAY VOID ANY SUPPORT | | AGREEMENT. If you do not agree to this -- or do not otherwise understand | | what you are doing -- you should type "exit" at the shell prompt. EVERY | | COMMAND THAT YOU EXECUTE HERE IS AUDITED, and support personnel may use | | this audit trail to substantiate invalidating your support contract. The | | operating system shell is NOT a supported mechanism for managing this | | appliance, and COMMANDS EXECUTED HERE MAY DO IRREPARABLE HARM. | | | | NOTHING SHOULD BE ATTEMPTED HERE BY UNTRAINED SUPPORT PERSONNEL UNDER ANY | | CIRCUMSTANCES. This appliance is a non-traditional operating system | | environment, and expertise in a traditional operating system environment | | in NO WAY constitutes training for supporting this appliance. THOSE WITH | | EXPERTISE IN OTHER SYSTEMS -- HOWEVER SUPERFICIALLY SIMILAR -- ARE MORE | | LIKELY TO MISTAKENLY EXECUTE OPERATIONS HERE THAT WILL DO IRREPARABLE | | HARM. Unless you have been explicitly trained on supporting this | | appliance via the operating system shell, you should immediately return | | to the appliance shell. | | | | Type "exit" now to return to the appliance shell. | +-----------------------------------------------------------------------------+ Cleaned up formatting

dahfizz 5y ago

It depends. If you give a reason why, it opens up the door for people to argue about whether the "why" is a valid justification. It also can make people feel like the "why" does not apply to them.

MaulingMonkey 5y ago
"why" can be pretty nebulous too. For a larger, widely used project, the question isn't "why" make something internal, but "why not". The safe default is to not semi-permanently commit every half baked bit of code to the public stable semvered API boundary to support for who knows how many years, but to only do so after careful consideration and justification. To add this disclaimer to every single bit of internal code is to drown your codebase in a sea of redundant comments - none of which are specific to the code, or even the codebase, but are instead rehashing "why encapsulation?" 101. This will only train readers of your code to ignore the low-value low-signal comments, and they will then end up asking the same question anyways, and "read the comment that's right there!!!111oneoneone" will be a fustrating experience for everyone, although they might not be able to articulate why. The real question I'm curious about here isn't "why are internal things internal" - but why this internal thing must technically be public. Does this predate ES6 symbols? Is there a plan to switch to those at some point in the future? Is there a tracking issue? Or does this need to be accessed from elsewhere in a manner that makes Symbols awkward to use? Where?

deleted 5y ago

[deleted]

Imnimo 5y ago

The "why" is that you will be fired, clearly :P

Grollicus 5y ago
I suspect they'll soon have an issue where someone wanted to get fired but it didn't work...
- MaxBarraclough 5y ago
  Interesting point. In naming it this way, the maintainers have committed to firing anyone who uses it, as an implicit guarantee of the public-facing API. Fortunately they're free to rename it in their next release. Perhaps something snappy like __secret_internals_do_not_use_or_version_specific_retribution_will_follow_possibly_including_firing

cbhl 5y ago

I wouldn't be surprised if there is a FB-internal comment (or commit message) that was stripped in the open source repos