I’m Bill I don’t comment my code (except complex parts), instead I try to make code clear, including using proper variable and function names and try to keep functions short. I don’t think I ever got lost in my own code in my 20+ years of experience. Even got complements about it.
The programming language is meant for humans to read/write, if you need to put comments to understand your code then your code sucks.
When writing basic business code, structuring the code well and having good naming standards means you shouldn’t need a ton of comments, but you should still have some. Plus, using structured function content blocks gives you intellisense in some languages and IDEs, which is important for code reuse in teams.
However, when I was doing scientific programming I’d have comments for almost every line at times where I put the mathematical formula and operations the line represents. Implementing a convolution neutral network with parameters to dynamically scale the layers or MPI stochastic simulations is much different than writing CRUD functions or basic business logic.
Wow this job has massive amounts of unnecessary stress, I wonder what the cause can be.
The cause is me, 6 months ago.
(Written for comedic purposes only. Managers are my single source of stress)
Me: writes code^1, doesn’t comment
Me, six months later: what idiot wrote this shit?!
- Only developer on project
Remembered*
Bill DID forget.
Comments are lies that will happen sometime in the future
Comments are always overlooked if gode gets refactored. Language servers can’t/won’t parse them and they’re easy to overlook.
If you name your functions/variables clearly, put complex logic into clearly named functions and keep the same level of abstraction in every function (which never exceeds roughly 50 lines), you hardly need any comments, if any.
Comments are for behavior that’s not possible to convey clearly through code.
If a block of code needs a comment, then you can easily move that block into a function and summarise the comment into a name for that function. If you can not easily move a block of code into a function, then you may need to rethink your design.
This isn’t always true of course, but it’s a good mindset to have.
I hate fixing other people’s code. It is one of the reasons I don’t like letting an AI write my code first draft either.