What’s the Best Way to Use AI for Improving Code Comments and Documentation?

AI-generated comments often merely explain the code's lower-level functions, which is useful for teaching, but in the real world, effective documentation dives into why the code is implemented a certain way. For instance, instead of 'strip special characters', a meaningful comment provides context: 'I need to strip characters because the input from the UI sometimes includes unwanted symbols.'

I get your intention, but I really think you should just focus on commenting manually. Comments are meant for you and other developers to understand your logic. AI tools might generate overly simplistic comments that could miss the nuances needed for real-world coding. For example, they might just say something generic like 'Set variable to array' instead of what you actually need to convey about why that code exists in the first place.

Honestly, none of the AI models will give you what you really want. Trust your own instincts and learn to write meaningful comments. Use your brain to develop your understanding of what the code is actually doing rather than relying on AI.

Honestly, relying too much on AI might not be the best path. You could be skipping valuable learning opportunities. The skill of writing good comments and documentation comes with practice, and doing it yourself will make you more proficient in the long run.

Using an AI isn't the best method to learn. Take the time to find a well-documented codebase and study it. You can see how to articulate why certain decisions were made rather than just what the code does at face value.

The effectiveness of AI tools for comments really hinges on how you instruct them. If you give them vague instructions, you won't get great results. You could ask an AI to help you frame your prompts around your specific needs, referencing examples of good and bad comments, or even better, ask it to teach you how to improve your own commenting skills.