Comment only in extraordinary situations, when something you read can confuse someone. And by that I mean the business logic, not that you used a method that’s confusing to people since they only know the basics of the language.
Honestly, after a few years of working with juniors (and being one myself before that), I have to disagree with the last part. Sure, it’s fine for solo projects but people’s programming skills can vary heavily. I know people who will pull the wildest C++ compile time tricks you’ve ever seen, but a pointer to a pointer would somehow break their brain.
I would disagree. I love to use comments to format my code and separate the sections. I think it’s so beautiful. Also I love when libraries have ASCII art in the comments at the top of the main file lol. It makes the code more fun in my opinion.
I went to college with a guy who would treat the code as art when presenting projects. His code was always beautiful. Not super functional but always beautiful. It always stuck with me. I want my code to always be functional and beautiful. Easy to read and a pleasure to work with. That’s my goal at least. Comments help with that.
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.
But then you write code in the real world and find out that you have to write some ass backwards code every other day because of deadlines, backwards compatibility or whatever, and suddenly you realize that despite your best efforts, code cannot always be self documenting.
Comments don’t describe the code. They describe the decision to use this business logic.
If you stick to good engineering practices, like small methods/functions, decoupling, and having testable code, you don’t often need many comments to show what your code does. I always recommend a method signature, though, because you can save a few seconds by just saying that a block of code does, rather than me needing to read exactly how you turned one dict into another dict…
I agree for inline code comments, like, “# Save the sprocket”, right above the line that saves the sprocket. Does this include documentation? Because when I see a prepareForSave function that references 10 other functions and I just want to know, “Is this mutating and how is it preparing for save and when should I call it?”, having the author spend 15 seconds telling me is less time consuming than me spending 5 minutes reading code to find out. Anyone who has read API docs has benefited from documentation.
No, commenting a function should be commonplace, if not only so that your IDE/editor can use the documentation when the signature is found elsewhere in your code.
Within a function, though, basically means that something gnarly is happening that wouldn’t be obvious, or that the function is doing more than it (probably) should.
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.
programmer_humor
Oldest
This magazine is from a federated server and may be incomplete. Browse more on the original instance.