Key Takeaways
Today, you learned that there’s more to comments than it seems. Once considered an afterthought, they’re now recognized an invaluable communication tool for programming.
- They help document and preserve knowledge for future code maintenance.
- There are good comments and bad comments.
- Comments can help create automated documentation.
Now, it’s time to practice! The only way to get good at comments is by jumping in and adding them.
By making comments part of your programming thought process, they no longer become an extra step to perform. Here are some ways to practice:
- Document your current projects and be mindful of any standards set for the project or repository.
- Use a linter on all your projects to keep your formatting and conventions in check.
- Find a document generator and publish your work.
You can practice and contribute while supporting an open-source project that needs help with comments and documentation.
Where to Go From Here?
If you’d like to learn more about commenting, check out these articles and resources. Many of them were consulted in the writing of this article.
We hope you’ve enjoyed this look at commenting! Do you have questions, suggestions or tips to share? Join us in the forum for this article. You can all learn from each other.
About the Author
Roberto Machorro has been programming professionally for over 25 years, and commenting code just as long. He has championed documenting in-house, third-party and open source code out of frustration for having to maintain badly written code or struggle with unavailable documentation. He got started with library documents using HeaderDoc, JavaDoc and now enjoying DocC.
