Moving all messaging into a module. Have them point to docs.

[fskreuz]

Description:

This has been running in my head for a while now. The idea is to have error messages link to dedicated error pages in the docs and have the messaging moved to a dedicated module. The former I think RequireJS and Angular 1 do it while the latter is just for ease of editing. Some advantages include:

• A contributor can easily find and update the message. No code hunting, less intimidation. Less-technical contributors (I think I fall under that category) can easily improve messaging.

• When messaging is associated with a predictable constant value, we can easily point it to a dedicated docs page. This allows the library to point the user to a resource immediately rather than ask in Github and wait until the end of the day for a reply.

  http://docs.ractivejs.org/${Ractive.VERSION}/debug/${errorConstant}
  
  // like
  
  http://docs.ractivejs.org/0.8/debug/RENDERING_ERROR

• For a production build, gobble can strip off the messaging. Less strings, therefore less in size.

  // Development build messaging. Has full explanation.
  
  Ractive Error: NON_PRIMITIVE_PROTOTYPE_DATA
  (detailed explanation on why you should use function-returned data)
  See http://docs.ractivejs.org/errors/NON_PRIMITIVE_PROTOTYPE_DATA
  (stack trace here)
  
  // Production build messaging. Only has the link.
  
  Ractive Error: NON_PRIMITIVE_PROTOTYPE_DATA
  See http://docs.ractivejs.org/errors/NON_PRIMITIVE_PROTOTYPE_DATA
  (stack trace here)

  There's 2 approaches I can think of:

  • Two builds for Ractive, debug and production. Kinda defeats the pending removal of legacy tho.
  • Ractive is built stripped of messaging and a separate script can augment messaging.

• With a production build (no messaging), there's less fluff in the console, especially when run on Node.

Ideas are very much welcome 😄

[JonDum]

Absolutely yes. Should save a good chunk of kb by removing those large debug strings.

[JonDum]

Also, can we standardize on DEBUG / PRODUCTION globals so Webpack/Uglify can automatically strip these out for us but we can use the unmin'd source?

if(DEBUG) {
    ...
}

becomes

if(false) {
   ...
}

Which Uglify/Closure will strip out completely because it's a no-op.

[dagnelies]

I'd vote against. :-1:

My reasons are the following:

• error messages are best placed within the code itself.
• you should understand the code producing the error message before editing the message anyway. Otherwise, you risk misleading, outdated or even wrong messages.
• when you edit related code, you directly see whether the message still makes sense.
• by providing links to external docs, you'll just create lots of additional pages you have to maintain, update, and keep in sync with the code. That's just a lot of work, and the docs are already struggling like it is to keep up-to-date.
• the messages are a small part of the lib, who cares if it's 3% bigger or smaller.
• there is already a Ractive.DEBUG flag.
• removing this code in production builds, to gain "a few kb", also means you are unable to live debug an application if you needed to. Personally, I would never sacrifice this for "a few kb", and I hope your webapp doesn't have a single image, otherwise it would defy the whole purpose of it.

---

To summarize it, this proposal adds an indirection that adds lots of complexity, favors out-of-sync code/messages, and lots of additional pages to maintain without offering benefits, besides the fact that people can erroneously update messages.