InsightSoftwareConsortium / InsightSoftwareConsortium/ITK

DOC: Formalize ITK policy for use of `auto`

Open Beginner friendly
#6,744 0 comments 1 reaction 0 assignees View on GitHub
area:Documentation type:Documentation
Dominant language
C++
Stars
1.7k
Forks
748
Avg merge
1d 1h
Merged PRs (30d)
64

Description

ITK has no written policy on when `auto` is appropriate, so every
mechanical-modernization PR re-litigates it in review.

The de-facto consensus that needs writing down

Surfaced in the review of #6014 (N-Dekker, dzenanz): ITK does **not**
follow "Almost Always Auto". `auto` is preferred where the type is
unambiguous from the initializer:

- factory calls — `Type::New()`, `Type::Filled()`, `MakeFilled()`
- explicit casts — `static_cast(...)`
- iterators and range-`for`
- structured bindings

and discouraged where it hides a numeric or pixel type that a reviewer
needs to see in order to judge the code.

Current documentation state

- `Documentation/AI/enforced-code-style.md` — mentions `auto` once, in an
`auto image = ImageType::New()` example. No rule.
- `Documentation/docs/contributing/` — no `auto` policy text at all.

Proposed deliverable

A short subsection in `Documentation/docs/contributing/` (mirrored into
`Documentation/AI/enforced-code-style.md`) with allow/avoid examples, so
mechanical modernization PRs have a citable rule instead of a per-PR
argument.

Related: #6014, #6044.

Contributor guide

Open the contributing guide

Research direction

Start by reading Documentation/AI/enforced-code-style.md and the contributing documentation under Documentation/docs/contributing/. Define the subsection around the stated factory, cast, iterator, range-for, and structured-binding cases, along with the numeric and pixel-type caution. Done means the policy and allow/avoid examples are present in the contributing documentation and mirrored in enforced-code-style.md.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.