MARSLib/old_standards.html at master · MARSProgramming/MARSLib · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
<!DOCTYPE html>
<html lang="en">
<head>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Orbitron:wght@400;500;600;700;800;900&family=Ubuntu:wght@300;400;500;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Core Standards ΓÇö MARSLib</title>
  <meta name="description" content="The definitive style guide and architectural ruleset governing the M.A.R.S. FRC codebase.">
  <link rel="stylesheet" href="assets/css/style.css">
  <link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css" rel="stylesheet" />
</head>
<body>

<div id="header-placeholder"></div>

<main class="container" style="padding-top: 100px; padding-bottom: 80px;">
  <div style="text-align: center; margin-bottom: 60px;">
    <a href="index.html" class="back-link">ΓåÉ RETURN TO BASE</a>
    <h1>THE MARSLIB STANDARD</h1>
    <p style="font-size: 1.25rem; color: var(--text-secondary); max-width: 700px; margin: 0 auto;">The definitive software engineering ruleset governing our World-Champion grade infrastructure. Code that violates these rules is rejected.</p>
  </div>

  <!-- Rule 1 -->
  <section class="rule-section">
    <span class="rule-num">01</span>
    <h2>Nullify Hungarian Notation</h2>
    <p>Using <code>m_</code> prefixes to dictate member variables is an archaic C++ practice that poisons Java IDE autocompletion and drastically reduces readability. MARSLib strictly bans Hungarian notation. We rely on modern syntax highlighting and the <code>this.</code> keyword for variable scope.</p>

    <div class="code-comparison">
      <div class="code-card code-bad">
        <div class="code-header">VIOLATION</div>
        <pre><code class="language-java">private final SwerveDrive m_swerve;
private double m_speed;

public void setSpeed(double speed) {
    m_speed = speed;
}</code></pre>
      </div>
      <div class="code-card code-good">
        <div class="code-header">MARS STANDARD</div>
        <pre><code class="language-java">private final SwerveDrive swerve;
private double targetVelocity;

public void setVelocity(double targetVelocity) {
    this.targetVelocity = targetVelocity;
}</code></pre>
      </div>
    </div>
  </section>

  <!-- Rule 2 -->
  <section class="rule-section">
    <span class="rule-num">02</span>
    <h2>The "Never Nester" Protocol</h2>
    <p>Code that is deeply nested across multiple <code>if/else</code> and <code>for</code> blocks is fragile and requires immense cognitive load to debug under competition pressure. All FRC control loops must remain completely "flat". Utilize guard clauses and early <code>return</code> expressions immediately.</p>

    <div class="code-comparison">
      <div class="code-card code-bad">
        <div class="code-header">VIOLATION</div>
        <pre><code class="language-java">public void shoot() {
    if (systemReady) {
        if (targetLocked) {
            if (flywheelAtSpeed) {
                feeder.run();
            }
        }
    }
}</code></pre>
      </div>
      <div class="code-card code-good">
        <div class="code-header">MARS STANDARD</div>
        <pre><code class="language-java">public void shoot() {
    if (!systemReady) return;
    if (!targetLocked) return;
    if (!flywheelAtSpeed) return;

    feeder.run();
}</code></pre>
      </div>
    </div>
  </section>

  <!-- Rule 3 -->
  <section class="rule-section">
    <span class="rule-num">03</span>
    <h2>Explicit Unit Nomenclature</h2>
    <p>A double named <span class="inline-code">speed</span> has destroyed billions of dollars in real-world aerospace missions. Passing raw sensor ticks or ambiguous integers into high-level functions is banned. Variables must describe precisely what they represent.</p>

    <div class="code-comparison">
      <div class="code-card code-bad">
        <div class="code-header">VIOLATION</div>
        <pre><code class="language-java">// What is 'tolerance'? Degrees? Radians?
// What is 'speed'? RPM? M/s? Volts?
public void setAngle(double angle, double tolerance) { ... }
public void runIntake(double speed) { ... }</code></pre>
      </div>
      <div class="code-card code-good">
        <div class="code-header">MARS STANDARD</div>
        <pre><code class="language-java">// Mathematically explicit parameters
public void setAngle(double radians, double toleranceRads) { ... }
public void runIntake(double voltageOut) { ... }</code></pre>
      </div>
    </div>
  </section>

  <!-- Rule 4 -->
  <section class="rule-section">
    <span class="rule-num">04</span>
    <h2>Zero-Allocation Architecture</h2>
    <p>Hot-paths (the 20ms and 4ms loops) must never use the <code>new</code> keyword to avoid JVM GC stalls. You must use globally instantiated Ephemeral Structs to proxy hardware parameters mathematically.</p>

    <div class="callout" style="background: rgba(41, 182, 246, 0.05); border-left: 4px solid var(--ai-cyan); padding: 24px; border-radius: 8px; margin: 30px 0;">
      <h4 style="font-family: 'Orbitron', sans-serif; color: var(--ai-cyan); margin-bottom: 10px; font-size: 1rem;">Mathematical Mutation</h4>
      <p>Do not pass structural pointers to objects that must preserve historic state (e.g. PID integrators). Always use <code>.clone()</code> if a downstream pipeline requires an immutable snapshot of an Ephemeral Struct.</p>
    </div>
  </section>

  <!-- Rule 5 -->
  <section class="rule-section">
    <span class="rule-num">05</span>
    <h2>Agentic Comments and Autonomy</h2>
    <p>MARSLib is the first FRC framework expressly co-developed with Artificial Intelligence. To instruct Claude Code or Z.ai agents efficiently, developers must leave explicitly structured block comments prefixing the exact file or mathematical function requiring augmentation.</p>
    <p>Code that is actively governed by an AI skill (such as Swerve Kinematics or Log Replay) must carry the <code>@AGENT_ENFORCED</code> JavaDoc tag to prevent human developers from breaking structured logic patterns.</p>
  </section>
</main>

<div id="footer-placeholder"></div>

<script src="assets/js/common.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-java.min.js"></script>
</body>
</html>