vuejs / vuejs/docs

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

Open
#3,345 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

discussion
Dominant language
Vue
Stars
3.2k
Forks
5k
Avg merge
14d 17h
Merged PRs (30d)
1

Description

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/guide/essentials/watchers.md at the “Basic Example” section linked in the issue, then read the surrounding computed-property and watcher introduction. Clarify the contrast between pure computation and watcher-triggered operations, while preserving the documented examples. Done means the introductory explanation no longer leaves the reference point for “side effects” ambiguous.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.