Skip to content

Issue with unclear reference point for "side effects" in the documentation #3345

@softworm

Description

@softworm

Computed properties allow us to declaratively compute derived values. However, there are cases where we need to perform "side effects" in reaction to state changes - for example, mutating the DOM, or changing another piece of state based on the result of an async operation.

watchers.md

I understand that in programming, a "side effect" refers to a function modifying system state beyond its primary task of returning a value. However, I find the usage in this specific context of the documentation somewhat confusing.

The documentation contrasts computed properties (which return derived values) with operations performed in watchers (like mutating the DOM or updating state), labeling the latter as "side effects."

The issue is:

  1. The "main effect" of a computed property—returning a value—is clear.

  2. However, in a watcher, there is no corresponding "main effect." The entire purpose of the watcher is to execute those very operations that are being called "side effects."

This makes the term "side effect" feel abrupt here, as there is no clear "main effect" to serve as a reference point.

Could the documentation perhaps:

  • More explicitly frame the comparison as "pure computation (no side effects)" vs. "the need to perform operations (which inherently involve side effects)"?

  • Or consider using more neutral terms like "reactive operations" or "state-triggered actions" in this introductory context?

This would help readers better grasp the distinction between these two concepts.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions