What can I solve with annotation templates?

A freeform note answers "what did someone write here?" A templated annotation answers a better question: "did everyone record the same things, so we can search, group, audit, and enforce them?" A template is a named set of fields — text, dates, droplists, radio choices, checkboxes — that turns notes into records.

This page maps the problems teams solve with them onto the concrete how-tos.

"Our MISRA deviations must be documented and approved — and prove it"

Every real MISRA/AUTOSAR program suppresses some violations, and the standard requires each deviation to be justified and approved. Mark a template as offered when ignoring a violation, and the Ignore Violation dialog becomes a deviation-record form:

Ignoring a violation with a template: the record is filled in as a form, and required fields must be answered before Apply.

The record travels inside the suppression itself — as Label: value lines in the code comment, or on an annotation in the project — and the Deviation Register report turns all of them into the table an auditor asks for, with the incomplete ones called out:

The register: every suppression, its record, and exactly what is missing from the ones that fall short.

How-to: Turn suppressions into deviation records, and Suppress a violation for the comment keywords themselves.

"Everyone writes review notes differently"

Code review verdicts, action items, ownership notes, technical-debt markers — freeform, they are prose only their author can find again. As templates, they are the same fields every time, so "every open High-priority action item" is a browsable group rather than a text search:

The Annotation Browser groups by template, then by field — assignees, priorities, verdicts — across the whole project.

How-to: Standardize team notes with annotation templates.

"Notes shouldn't rot — or leak into the source"

Annotations live in the Understand project, not in the code (unless you choose the in-code comment form for a suppression). Templates are shared with the team through the project's annotation_templates.json, so the whole team offers the same forms. Fields can default from context — $Author, $Date, $FileShortName — so half the record fills itself:

A completed record reads as text on the card; the fields are still data underneath.

How-to: sharing and defaults are covered in Standardize team notes with annotation templates.

"A deviation with no justification should fail the build"

An ignore that names a template but leaves required fields unanswered is reported as a CodeCheck analysis error — on every analyze, in the GUI's Inspection Errors and in und output alike. In CI, und codecheck -exitstatus errors turns that count into the exit status, so an undocumented deviation fails the pipeline the moment it is written, not at audit time:

The summary page tracks completeness over the whole inspection — one number for the standup, one chart for the review.

How-to: Run CodeCheck in CI, and the completeness details in Turn suppressions into deviation records.

"We classify thousands of entities, not one at a time"

und annotate applies a template from the command line, to every entity a search matches, with $parameters expanded per target — one command classifies every file by component, or stamps every entity in a directory with an owner. See the und annotate reference and Standardize team notes.

Where the records go next

Everything a template records is plain, structured data:

• Reports — the Deviation Register and the standards reports (Guideline Compliance Summary, Deviation Approval Records, Risk Assessment, Accepted Risk Register), and Annotations by Template for coverage of every structured note, suppression or not.
• Scripts — atn.text() returns the annotation with its record inlined as Label: value lines; a violation's suppressions arrive the same way through Viol.ignores().
• Exports — annotation CSV exports carry the fields as columns.