Code Quality: Terminology #74427

New Issue

Sergey Sharybin · 2020-03-04T12:24:03+01:00

Sergey Sharybin commented

2020-03-04 12:24:03 +01:00

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.

# 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.

Sergey Sharybin commented

2020-03-04 12:24:03 +01:00

Changed status from 'Needs Triage' to: 'Confirmed'

Sergey Sharybin commented

2020-03-04 12:24:03 +01:00

Added subscriber: @Sergey

Sergey Sharybin changed title from ~~Code Quality Day Tasks: Terminology~~ to Code Quality: Terminology

2020-03-04 12:24:43 +01:00

Philipp Oeser removed the

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Code Quality: Terminology #74427

Code Quality Day: Terminology

Overview

Explanation/reasoning/motivarion

Verify

Validate