Software Design/Discoverability

Discoverability is a code, interface, and software quality. Code discoverability characterizes how easy or hard it is for a developer to find the functionality already existing in the codebase or entities related to or dependent on some other entity, for example:

• Endpoints exposed by a server system.
• Code using a certain variable, function, or class.
• Classes implementing a certain abstract class.

Interface (API) discoverability characterizes how easy or hard it is for a user of the interface to find relevant functionality.

Code and interface discoverability is not a pure software design concern. It also depends on the tools which are used to browse and edit the software. For example, the usage of wildcard import statements (available in most programming languages), as well as static imports in languages such as Java doesn't make it harder to find usage of a variable or a function from an IDE, but may complicate this kind of discoverability when the codebase is browsed from command line or a plain-text editor.

Examples

SPI artchitecture of an application with modules possibly defined in different codebases and assembled in runtime or on the configuration level might make hard to discover API endpoints of a service (software discoverability) unless the web framework provides a discovery/documentation page at some conventional path, such as /docs.

In object-oriented programming languages, the dot notation for calling functions (like object.doSomething()) aids API discoverability because IDEs could suggest the developer functions which could be called with the given object as the reciever.

On the other hand, the fact that most of the logic written in functional programming languages is decomposed into pure functions makes search by function's type signature an effective way to discover library functionality. This is implemented in services like Hoogle for Haskell and FSDN for F#.

Relations to other qualities

Consistent naming aids API discoverability because users could assume how functions or REST API endpoints with certain functionality may or may not be called. Structuredness may also allow users to guess with confidence in which module (class, API domain, etc.) the sought-for functionality is located.

Relevant practices

• Hide an object access chain
• Link to related functions in the documentation for a function
• Build an object-based API
• Make RPC calls discoverable in code