Comments are the one part of a program the machine is explicitly told to ignore, which makes them the only part written purely for people: the next operator, the day shift, you in six months. The mechanics take two minutes to learn, the dialect rules one more, and the craft, what a comment should actually say, is where programs become either self-documenting or archaeologically hostile.
Why G-code comments are stranger than they look
Most programming languages designed their comment syntax; G-code inherited its constraints from hardware. Parentheses were chosen in an era when the character set was tiny and every byte of tape had a cost, which is why the format is minimal: one opener, one closer, no nesting, no escapes, no block-comment luxury. The semicolon style arrived decades later from the computing side, and the two now coexist across dialects without a referee. The result is a comment system where the rules are simple but the edges are sharp, and where one missing character can do structural damage no modern language would allow.
The two styles and where they work
| Style | Form | Where it dominates |
|---|---|---|
| Parentheses | G01 X50. (FINISH PASS) F200 | Fanuc-compatible controls; the classic industrial form |
| Semicolon to end of line | G01 X50. F200 ; finish pass | LinuxCNC, GRBL, and 3D-printer dialects |
Parenthetical comments open and close anywhere in a line, can sit mid-block between words, and are the form most industrial posts emit. The semicolon style comments out everything from the character to the line’s end, simpler, but only available where the dialect grants it, the LinuxCNC overview documents both forms plus its message extensions, while GRBL-class controllers handle both styles in their own documented way. Many modern controls accept both; some accept exactly one; the file your post emits already chose correctly for its target, and hand-written code should copy whatever the machine’s existing programs use.
The universal rules
Three rules hold across every dialect that has comments at all. No nesting: the first closing parenthesis ends the comment, so a comment containing parentheses ends early and spills its tail onto the line as garbage. Write comments flat. Never split a word: a comment between G and 01 breaks the word; comments live between words, not inside them. Close what you open: the unclosed parenthesis is the greedy-comment trap, on permissive parsers it can swallow code silently, shortening the program without an error, the comment family’s cousin of the missing decimal point: tiny, legal-looking, structural. It is also exactly the kind of defect regex-based file checks catch in one pass, and editors that highlight comment spans make it visible by color.
One boundary note: comments are not free real estate everywhere in the file. The territory around file markers and program numbers has its own per-control rules, and the safe pattern is keeping comments inside the program body, attached to the lines they describe.
What comments should say
The craft rule: the program already says what; comments earn their space saying why and which. Three categories carry nearly all the value. Operation labels make programs navigable, (T3 FINISH BORE), (OP2 FLIP), the headings an operator scrolls by, the difference between finding a restart point in seconds versus minutes. Setup assumptions state what the code cannot, (Z0 IS TOP OF STOCK), (G54 SET TO FIXTURE A), the contract between programmer and setup. The why of unusual lines protects deliberate decisions from future helpfulness: (FEED REDUCED, THIN WALL) stops the next editor from optimizing a limp back into a chatter problem. The anti-pattern is the echo comment, (SPINDLE ON) beside M03, which adds reading load and zero information; if a reader needs M03 translated, the answer is vocabulary fluency, not subtitles. Brevity has a mechanical bonus too: machine-generated marathon comments are the lines that actually trip per-control length limits, and short purposeful comments never meet that problem.
Message and display extensions, comments the control surfaces to the operator at runtime, exist per dialect for setup instructions and operator prompts, and they follow the same craft rule at higher stakes: a message interrupting a cycle should say something the moment needs.
The habit that makes it stick
Comment as you write, not after: the assumptions are in your head exactly once. A program commented in that pass hands the night shift its own documentation, labels to navigate by, assumptions to verify, reasons to respect, and costs the writer minutes. The reading side of the bargain, scanning code fast enough that the comments are wayfinding rather than life support, is the recall fluency the free 60-second drills on the G-code practice page build; the writing side is this page, applied once per program, forever.
Sources
Frequently asked questions
How do you add comments in G-code?
Two styles, by dialect: parentheses open and close a comment anywhere in a line, the classic Fanuc-compatible form, and the semicolon comments everything to the line’s end, common in LinuxCNC and GRBL. Your control’s documentation settles which apply; the content rules are universal.
Can you nest parentheses in G-code comments?
No. The first closing parenthesis ends the comment, and the rest spills onto the line. Write comments flat; the format has no escape mechanism.
What is the greedy comment trap?
An unclosed parenthesis: on permissive parsers it can swallow code silently, shortening the program without an error. Editors that highlight comment spans and one-pass file checks catch it.
What should comments in a CNC program actually say?
What the code cannot: operation labels, setup assumptions, and the why of unusual lines. Comments that restate the code add reading load without information.