Is it normal to spend more time writing comments than actual code?

Oct 14, 2026 Last reply: 1 day ago 5 Replies

First reply

Sam_Tundra

You're not alone, and honestly the register config comments are the one place I'd defend heavy commenting without hesitation. I keep a little notebook habit going where every timer setup gets a block at the top explaining the math: clock in, what the prescaler divides it down…

Read the full reply

So I've been writing a little software PWM thing on an STM32 for a hobby project, and I noticed something wierd about myself. I'll spend a whole evening getting the timer config right, and then another evening writing comments explaining every single line to future me. Like, paragraphs. With little diagrams made of slashes and asterisks. It's honestly the part I look forward to most.



The thing is, my buddy who codes for a living says I'm wasting my time. He says good code explains itself and comments go stale anyway. And I get that arguement, but when I come back to a project three months later, those comments have saved me more times than I can count. especally when I forgot why I set some weird prescaler value that made no sense at first glance.



Am I alone in this? Do other people here actually enjoy writing the documentation part, or is everyone just slapping in a one-liner and moving on? Sometimes I wonder if I'm using comment writing as an excuse to procrastinate on the hard debugging stuff, if I'm being honest with myself.


You're not alone, and honestly the register config comments are the one place I'd defend heavy commenting without hesitation. I keep a little notebook habit going where every timer setup gets a block at the top explaining the math: clock in, what the prescaler divides it down to, what the overflow period works out to, and why I picked those numbers instead of the obvious round ones. becuase three months later, that weird value that makes no sense at first glance ussually made perfect sense when I was fighting a specific problem, and without the comment I'll 'fix' it right back into the bug I originally squashed.

Your buddy's argument kind of falls apart with timing stuff though. Self documenting code can't tell you why the numbers are what they are, only what they are. What fixed this for me was dumb simple, a plain text template I keep in my snippets folder with blank fields: clock source, target tick rate, anything weird I had to work around. Copy paste it above every peripheral setup, fill in the blanks, done in ten minutes. Made the whole thing feel like less of an event. And honestly if commenting IS your procrastination, that's the good kind. Beats doom scrolling between debug sessions.

The procrastination bit hits home. I've definatly polished a comment block while avoiding a stubborn bug that ended up being a floating input pin the whole time. But here's the thing that sold me on it: my kid wanted to mess with one of my boards last year and the comments were the only reason he got anywhere. I'd written them for me, but they turned out to be the manual the chip never came with. Now I just accept that some evenings are comment evenings and stop feeling guilty about it.

Honestly as someone only a few months into this stuff my comments end up being half questions. I'll write stuff like 'does this even need to be this high?' right above a line, and then weeks later when I finally figure out the answer I go back and answer my own question in the comment. It's weirdly become my main way of learning, like leaving notes for the version of me that doesn't know anything yet. Is that a normal way to do it or am I just making work for myself? Feels like it might fall apart once I actually know what I'm doing.

Gotta push back on the notebook habit a bit though. Every comment block like that I've ever written went stale the first time I changed a divider and forgot to redo the math above it. Now I had a comment confidently explaining numbers that were wrong, which is worse than no comment. What works for me is keeping the reasoning next to the change instead, so a one line note in the commit about why I bumped the speed, plus a variable name that says what it means. The comments I still write are only for the stuff that looks like a mistake, like that one weird delay I had to add or the code just looks broken.

Join the Discussion

Have something to add? Share your thoughts — no account required.

Didn't find your answer?

Ask the community — no account required