/cc @nathansobo @benogle

from api.

Can you give an example of what you mean by "helper method"?

from api.

Config is a good example to explain helper methods and other examples of things
I would like to fix.

Here is the current API for config with usage stats

Config                                                       called packages atom packages
--
::get(keyPath)                                               732    250      21
::observe(keyPath, options, callback)                        149    80       10
::set(keyPath, value)                                        70     30       4
::unobserve(keyPath)                                         38     26       0
::toggle(keyPath)                                            9      4        2
::getSettings()                                              8      6        1
::getDefault(keyPath)                                        5      3        1
::getPositiveInt(keyPath, defaultValue)                      4      4        2
::getInt(keyPath)                                            2      2        0
::getUserConfigPath()                                        1      1        0
::pushAtKeyPath(keyPath, value)                              0      0        0
::unshiftAtKeyPath(keyPath, value)                           0      0        0
::removeAtKeyPath(keyPath, value)                            0      0        0
::isDefault(keyPath)                                         0      0        1
::restoreDefault(keyPath)                                    0      0        0

Here is what I would like Config to look:

Config                                                         called packages atom packages
--
::get(keyPath)                                               732    250      21
::observe(keyPath, options, callback)                        149    80       10
::set(keyPath, value)                                        70     30       4

Helper Methods

I'm defining helper methods as a method that can be recreated using other API
methods. They exist for convenience and can be recreated with a few lines of
code. I consider getPositiveInt, getInt, toggle, pushAtKeyPath and
removeAtKeyPath all helper methods.

Misused methods

• getSettings

  This method should be renamed because it is confusing to mix settings and
  config. SettingsView is the only package that uses this method correctly. All
  other packages use it like this:

  var config = atom.config.getSettings()['atom-beautify'];

  Clearly they should be using Config::get instead of getSettings

• getDefault

  SettingsView is the only package that uses this method correctly. All other
  packages use it like this:

  value = atom.config.get 'sublime-tabs.' + "#{key}"
  value ?= atom.config.getDefault 'sublime-tabs.' + "#{key}"
  

  when all they need to do is call

  value = atom.config.get 'sublime-tabs.' + "#{key}"
  

from api.

How can ::pushAtKeyPath be replicated in terms of the other methods?

from api.

Wouldn't this work?

array = atom.config.get(keyPath) ? []
array.push(value)
atom.config.set(keyPath, array)

from api.

Yep. 😿

from api.

Based on meetings we've had, I think I can safely say the Atom team disagree with most of this philosophy. But I'd still like to read an overview of the rest of the team's API philosophy.

from api.

the Atom team disagree with most of this philosophy

@probablycorey can you add more context to this statement? Do you mean the team disagrees with the issue as stated at the top? Or something else?

from api.

I think we actually do agree with most of it, but we did not agree on removing a significant portion of the existing public API, including some methods you could describe as "helper methods". As a compromise, we've decided to segment the API into "essential" and "extended". New users can start with the essential API as a more digestable introduction to programming Atom, while more advanced methods used in packages remain in the scope of the public contract via the extended API.

from api.

👍

from api.