I'm training to become a junior QA Automated Testing Engineer and I'm struggling with what to include in my method comments. My IDE prompts me to fill out both a summary and a returns section, but I often find myself writing comments for methods that do very little. For example, in a method where I'm returning string prompts for navigating HTML input tags while web scraping with Selenium, I'm unsure if I should just restate what the method does in both sections, or if there's a better approach to making my comments more professional. How detailed should these comments really be?
4 Answers
It really depends on your team and project style. I believe the summary should say what's happening, like 'Gets all of the PageInputSets prompts', while the returns section could explain the return type as 'An iterable, read-only collection of strings'. This way, it doesn't become repetitive.
Honestly, you don't always need both a summary and a returns section for simple functions. If the method name is clear enough, people might already understand its purpose without extra context. For instance, instead of your current method name, consider 'GetPrompts' for more clarity.
The type information is evident in the code itself, so you don't need to spell it out in your comments. A better summary might explain the significance of what the function returns or its effect when called. Reserve the returns comment for something meaningful relating to the result.
I think both the summary and returns are a bit too detailed as is. You can simplify it! Just have a summary like 'Get the prompts' and a returns section that says 'a collection of prompts'. The method signature already indicates it's read-only, so don't overcomplicate it.
Related Questions
How To: Running Codex CLI on Windows with Azure OpenAI
Set Wordpress Featured Image Using Javascript
How To Fix PHP Random Being The Same
Why no WebP Support with Wordpress
Replace Wordpress Cron With Linux Cron
Customize Yoast Canonical URL Programmatically