Skip to content

Avoid weasel words/justification filler phrases #761

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Avoid weasel words/justification filler phrases #761

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c6b20b3
Avoid weasel words/justification filler phrases
MatheusRich May 22, 2025
e6b7cc2
typo
MatheusRich May 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions code-review/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ Watch a presentation that covers this material from [Derek Prior at RailsConf 20
- **Avoid diminishing words**
- "simply", "simple", "just"

- **Avoid [weasel words]/[justification filler phrases]**
- "Researchers say that", "it's a best practice".
- Be clear and explain the tradeoffs and impacts of a particular solution.
Comment on lines +30 to +32
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: What you you think about inverting the framing to present the guideline in a positive lens?

I feel like your third bullet point is the core concept here, the meat of what the guideline is getting at. What would you think of surfacing that as the primary idea?

Perhaps something along the lines of:

Suggested change
- **Avoid [weasel words]/[justification filler phrases]**
- "Researchers say that", "it's a best practice".
- Be clear and explain the tradeoffs and impacts of a particular solution.
- **Strive for clarity and articulate your reasoning.**
- explain the forces, considerations, trade-offs and/or impacts behind your feedback or suggested solution.
- It's helpful to avoid [weasel words]/[justification filler phrases] — "Researchers say that", "it's a best practice".

I'd argue that avoiding filler phrases and weasel words alone won't increase the information communicated. It would remove the impression of communicated information that can lead to ambiguity. The removal would need to be coupled with added explanation/articulation of one's reasoning. Similarly, feedback that fully explained one's reasoning, yet happened to include some weasel words or filler — while being a bit verbose and having room for improvement — would fully communicate one's reasoning.

Some reasons to consider a positive framing over negative framing because:

  • a positive frame tends to surface the concept or theory behind the guideline
  • a positive orientation emphasizes things that can be added (an opportunity for growth or what can be gained)
  • a negative frame emphasizes the fault or lack of something
  • when pointing out what not to do, it can be easy to forget to mention what to do instead (Though you do provide an alternative and preferred approach).
  • too many rules of "what not to do" can start to feel restrictive/legalistic/pedantic/puritanical/bureaucratic (not sure I'm finding the right word)

ref - https://notes.andymatuschak.org/z63PA5ATVi8oyhyLgeGvL3p
ref - https://www.nicolecw.com/marketing/copywriting-positive-framing-negative-framing/

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm torn about that. While I like the positive framing, I fear it becomes too generic (too similar with the first bullet point in this file).

I'll let others chime in and leave their thoughts. If folks prefer the positive version, I'll update it. Thank you!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it's similarity to other guidelines, is there an opportunity for a larger refactoring? (I can't quite think of what that might look like though).


- **Be explicit**
- Remember people don't always understand your intentions online.

Expand Down Expand Up @@ -133,3 +137,5 @@ This helps us have more meaningful conversations on PRs rather than debating per
[challenging to convey emotion and intention online]: https://thoughtbot.com/blog/empathy-online
[using labels]: https://conventionalcomments.org
[standard]: https://github.com/testdouble/standard
[weasel words]: https://en.wikipedia.org/wiki/Weasel_word
[justification filler phrases]: https://serce.me/posts/2025-05-19-justification-filler-phrases