Comprehension
Category: Comprehension v0.12 result: Calor wins (1.84x across 217 programs) What it measures: Structural clarity and semantic extractability
Overview
The Comprehension metric measures how easily an AI agent can understand code structure and extract semantic information without deep analysis.
Why It Matters
When an AI agent reads code, it needs to answer:
- What are the function boundaries?
- What are the inputs and outputs?
- What side effects are possible?
- What constraints must hold?
Traditional languages require parsing and inference. Calor makes these explicit.
How It's Measured
Calor Clarity Factors
| Factor | Points | Check |
|---|---|---|
| Module declaration | 0.15 | Contains §M{ |
| Function declaration | 0.15 | Contains §F{ |
| Input parameters | 0.10 | Contains §I{ |
| Output type | 0.10 | Contains §O{ |
| Return statement | 0.10 | Contains §R |
| Effect declaration | 0.15 | Contains §E{ |
| Requires contract | 0.15 | Contains §Q |
| Ensures contract | 0.10 | Contains §S |
| Indented body line (proportional) | up to 0.10 | Matches ^[ \t]+\S |
| Indent-form completeness | 0.05 | At least one indented body line per §F{ opener |
C# Clarity Factors
| Factor | Points | Check |
|---|---|---|
| Namespace | 0.15 | Contains namespace |
| Class | 0.10 | Contains class |
| Public modifier | 0.05 | Contains public |
| Private modifier | 0.05 | Contains private |
| Return statement | 0.10 | Contains return |
| XML documentation | 0.20 | Contains /// |
| Comments | 0.05 | Contains // |
| Type annotations | 0.10 | Contains int , string , etc. |
| Code Contracts | 0.15 | Contains Contract. or Debug.Assert |
Example Comparison
Calor (High Clarity)
§M{m001:Calculator}
§F{f001:Divide:pub}
§I{i32:a}
§I{i32:b}
§O{i32}
§Q (!= b 0)
§S (>= result 0)
§R (/ a b)Score calculation:
§M{: +0.15§F{: +0.15§I{: +0.10§O{: +0.10§R: +0.10§Q: +0.15§S: +0.10- Indented body lines: +0.10 (proportional)
- Indent-form completeness (every
§F{has an indented body): +0.05
Total: 1.00
C# (Lower Clarity)
namespace Calculator
{
public static class Program
{
public static int Divide(int a, int b)
{
if (b == 0) throw new ArgumentException();
var result = a / b;
Debug.Assert(result >= 0);
return result;
}
}
}Score calculation:
namespace: +0.15class: +0.10public: +0.05return: +0.10int: +0.10Debug.Assert: +0.15
Total: 0.65
Illustrative ratio: 0.95 / 0.65 = 1.46x. This single example is not the aggregate v0.12 result.
What Agents Can Extract
From Calor (Direct Extraction)
| Information | Extraction Method |
|---|---|
| Function name | Parse §F{id:name:vis} |
| Function ID | Parse §F{id:name:vis} |
| Inputs | Find all §I{type:name} |
| Output type | Parse §O{type} |
| Side effects | Parse §E{codes} |
| Preconditions | Find all §Q condition |
| Postconditions | Find all §S condition |
| Scope boundaries | §F{id} opener followed by indented body lines (terminated by dedent in indent form) |
From C# (Requires Inference)
| Information | Extraction Method |
|---|---|
| Function name | Parse method declaration |
| Inputs | Parse parameter list |
| Output type | Parse return type |
| Side effects | Analyze all statements for I/O |
| Preconditions | Find throw statements, Debug.Assert |
| Postconditions | Find assertions near return |
| Scope boundaries | Count and match braces |
Real-World Impact
Agent Task: "What are the constraints on the Divide function?"
From Calor:
Preconditions: b != 0
Postconditions: result >= 0Direct extraction from §Q and §S.
From C#:
Must analyze:
1. Exception throws (if (b == 0) throw...)
2. Debug.Assert calls
3. Comments (if any)
4. Infer from implementationInterpretation
The v0.12 aggregate is 1.84x. Under this calculator, Calor source exposes more of the structural signals being counted. That measures the calculator's defined signals; it is not a direct measurement of human comprehension.
This doesn't mean C# is hard to understand—it means Calor makes structure more explicit, which benefits automated analysis.
Next
- Error Detection - How contracts help find bugs