Page MenuHome

Code Quality: Terminology
Confirmed, NormalPublicDESIGN

Description

Code Quality Day: Terminology

https://wiki.blender.org/wiki/Style_Guide/Code_Quality_Day

Overview

  • Remove use of the term 'verify' since it's used ambiguously.
  • Avoid use of the term 'validate' since it's used ambiguously,

Explanation/reasoning/motivarion

Verify

Term verify is ambiguous and better naming exists.

  • Return an item if it exists, otherwise create a new one (use ensure instead of 'verify').

eg:

  • defvert_verify_index -> defvert_ensure_index
  • BKE_image_verify_viewer -> BKE_image_ensure_viewer

Most instances can be changed, although there are some exceptions, eg: RNA_define_verify_sdna could be left as is, or renamed to something more explicit.

Validate

Ambiguous term: from dictionary.com "to make valid; substantiate; confirm"

We have examples that:

  • Return false, on invalid data.
  • Raise an error and early-exit on invalid data.
  • Fix the invalid data, returning true - when the data was modified.
  • Correctness check (immutable), (use is_valid instead of 'validate').
  • Make something valid (mutable) (use sanitize instead of 'validate').

For data which stores a flag for it's correctness - a function that updates this could be called 'validate', also cache validation sense, in most cases this is not what it's used for.

Note that this is used in many places over the API, although reading over the current usage confirms that this is used confusingly.

Related Objects

StatusSubtypeAssignedTask
ConfirmedTO DONone
ConfirmedDESIGNNone

Event Timeline

Sergey Sharybin (sergey) renamed this task from Code Quality Day Tasks: Terminology to Code Quality: Terminology.Mar 4 2020, 12:24 PM
Sergey Sharybin (sergey) changed the task status from Needs Triage to Confirmed.
Sergey Sharybin (sergey) created this task.