From f3514f452051dc157f1aa01d1c9df21970a455d4 Mon Sep 17 00:00:00 2001 From: Simon Heybrock Date: Thu, 20 Jun 2024 05:17:15 +0200 Subject: [PATCH 1/4] Replace strict type var naming convention --- docs/user-guide/reduction-workflow-guidelines.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/user-guide/reduction-workflow-guidelines.md b/docs/user-guide/reduction-workflow-guidelines.md index 14c9f3e3..d35fa0a4 100644 --- a/docs/user-guide/reduction-workflow-guidelines.md +++ b/docs/user-guide/reduction-workflow-guidelines.md @@ -92,13 +92,16 @@ RunType = TypeVar('RunType', SampleRun, BackgroundRun) class Filename(sciline.Scope[RunType, str], str): ... ``` -### C.3: Use the suffix 'Type' for type vars +### C.3: Carefully choose names of type vars **Reason** -This makes it easier to distinguish type vars from concrete domain types. +It is important that type vars can be distinguished from concrete domain types, and that it has a clear meaning. **Example** -See 'RunType' and 'MonitorType' in the table of C.2. + +- `RunType` and `MonitorType` are examples where having the suffix `Type` can be useful, since `Run` could be confused with (or used as) a domain type giving the run number. + See 'RunType' and 'MonitorType' in the table of C.2. +- `PolarizerSpin = TypeVar['PolarizerSpin', Up, Down]` probably does not require a `Type` suffix. ### C.4: Use flexible types From b9c8b88d305ffc66230c2e985bdbd49ffbdf06d9 Mon Sep 17 00:00:00 2001 From: Simon Heybrock Date: Mon, 24 Jun 2024 07:16:03 +0200 Subject: [PATCH 2/4] Revert "Replace strict type var naming convention" This reverts commit f3514f452051dc157f1aa01d1c9df21970a455d4. --- docs/user-guide/reduction-workflow-guidelines.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/reduction-workflow-guidelines.md b/docs/user-guide/reduction-workflow-guidelines.md index d35fa0a4..14c9f3e3 100644 --- a/docs/user-guide/reduction-workflow-guidelines.md +++ b/docs/user-guide/reduction-workflow-guidelines.md @@ -92,16 +92,13 @@ RunType = TypeVar('RunType', SampleRun, BackgroundRun) class Filename(sciline.Scope[RunType, str], str): ... ``` -### C.3: Carefully choose names of type vars +### C.3: Use the suffix 'Type' for type vars **Reason** -It is important that type vars can be distinguished from concrete domain types, and that it has a clear meaning. +This makes it easier to distinguish type vars from concrete domain types. **Example** - -- `RunType` and `MonitorType` are examples where having the suffix `Type` can be useful, since `Run` could be confused with (or used as) a domain type giving the run number. - See 'RunType' and 'MonitorType' in the table of C.2. -- `PolarizerSpin = TypeVar['PolarizerSpin', Up, Down]` probably does not require a `Type` suffix. +See 'RunType' and 'MonitorType' in the table of C.2. ### C.4: Use flexible types From 0ea86a499c1ba8ca41a4703439d5dc2a52430c5c Mon Sep 17 00:00:00 2001 From: Simon Heybrock Date: Mon, 24 Jun 2024 07:18:06 +0200 Subject: [PATCH 3/4] Remove rule about TypeVar naming --- docs/user-guide/reduction-workflow-guidelines.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/user-guide/reduction-workflow-guidelines.md b/docs/user-guide/reduction-workflow-guidelines.md index 14c9f3e3..b847649b 100644 --- a/docs/user-guide/reduction-workflow-guidelines.md +++ b/docs/user-guide/reduction-workflow-guidelines.md @@ -92,13 +92,7 @@ RunType = TypeVar('RunType', SampleRun, BackgroundRun) class Filename(sciline.Scope[RunType, str], str): ... ``` -### C.3: Use the suffix 'Type' for type vars - -**Reason** -This makes it easier to distinguish type vars from concrete domain types. - -**Example** -See 'RunType' and 'MonitorType' in the table of C.2. +### C.3: (Removed rule on naming TypeVars) ### C.4: Use flexible types From 8a2f1623f1eb2ad575da43ac739bb33ab81eee2d Mon Sep 17 00:00:00 2001 From: Simon Heybrock <12912489+SimonHeybrock@users.noreply.github.com> Date: Mon, 24 Jun 2024 09:53:13 +0200 Subject: [PATCH 4/4] Update docs/user-guide/reduction-workflow-guidelines.md Co-authored-by: Jan-Lukas Wynen --- docs/user-guide/reduction-workflow-guidelines.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/user-guide/reduction-workflow-guidelines.md b/docs/user-guide/reduction-workflow-guidelines.md index b847649b..d892c1b9 100644 --- a/docs/user-guide/reduction-workflow-guidelines.md +++ b/docs/user-guide/reduction-workflow-guidelines.md @@ -94,6 +94,9 @@ class Filename(sciline.Scope[RunType, str], str): ... ### C.3: (Removed rule on naming TypeVars) +This guideline was too restrictive as not all TypeVars represent a "type", conceptually. +Instead, authors should apply good judgment when naming TypeVars. + ### C.4: Use flexible types **Reason**