I'm diving into creating my first game using SFML with C++, but I've hit a snag. The tutorial I'm following is based on SFML 2.5, while I have the 3.0 version files. To adapt, I'm reading through the documentation and incorporating that into my code updates. This method definitely enhances my understanding more than the YouTube explanations. However, I'm struggling to find the balance with my comments. I want to provide plenty of notes, but it's making my code cluttered and hard to read. Should I opt for multi-line comments for everything or stick to cleaner single-line comments and just reference the documentation when needed? Is it worthwhile to write these single-line comments and then also keep detailed handwritten notes for better memorization? Or should I just seek out a tutorial that uses SFML 3.0 instead?
6 Answers
You can add a few comments before big blocks of code to outline what you're doing. For tricky lines, inline comments are fine too. Remember, this coding journey is for you, so jot down notes that resonate with you!
My professor used to say comments should match the amount of code. It helps when others are involved too! A good rule is to keep comments meaningful but not overwhelming; they should help, not hinder.
Honestly, don't stress about perfect sentences. Since you're the only one really looking at your code, write your comments in a way that makes sense to you, and keep it casual!
If you're finding the comments useful, go for it. There’s no 'comment police' to stop you! Just remember, if you plan to reuse this code later, think about how you'd understand your notes down the line. Notes work better for broad concepts outside the code, while comments should clarify specific parts and choices you've made.
Use docstrings before functions and methods according to common standards, and keep short comments for significant lines—things that are tricky or important in your code. If you’re commenting every line, that might be overkill!
Try to write self-documenting code. Meaningful variable names and clean organization can make your code tell its own story. If you need a lot of comments, it might signal that the code needs some simplifying. But if something's tricky for you, it's likely tricky for others too, so that's worth noting!
I see your point, but I prefer using comments as personal study notes too. I just try to keep the big ones at the top of functions to keep things clean. Whatever works for you!