What’s the best way to write comments in code?

If you're looking for tips on writing good comments, there are plenty of great blog posts out there! Generally, comments should focus on the 'why' behind your code rather than just the 'how'. Think about what would help you or someone else understand the code if they came back to it months later. It's all about providing context, and it's a skill that improves with practice, so try not to stress too much in the beginning!

Try to put yourself in the shoes of someone with no background knowledge of your code. That's what comments are for! Sometimes the code is clear, and other times it needs detailed context. There's no hard and fast rule; avoid thinking you must comment every line or function — adapt as needed!

I usually write comments when the code isn't straightforward. For example, if a for loop isn’t obviously necessary, I’ll add a comment explaining it. My goal is to make sure the code can speak for itself, but if something might confuse someone later, then I'll comment on it. After finishing the code, I read it through as if I'm a stranger to it. If something doesn’t click right away, I make a brief note. Just keep comments for the tricky parts!

A good rule of thumb is if you can't explain a function in a simple sentence, it may be too complex. Consider breaking it down into smaller functions. Always think about what information would be helpful to someone reading your code who knows nothing about it. But don’t feel pressured to comment every single detail; let the code do some talking too!

Comments can be really useful for conveying things that might not be obvious just from reading the code. Often, this means explaining business logic or clarifying why you're doing something a certain way. For instance, noting that 'if this check fails, it indicates xyz has occurred elsewhere' can be really helpful. Remember, good function and variable names often explain things well enough, but cases like parsing or complex logic might need some inline comments.

Keep your comments short and to the point! If you find yourself writing long comments, that might mean you need to break your function into smaller pieces to clarify things. Concise comments are more effective!