In this new post to his site Jani Hartikainen suggests a few things you can do to help make your code "self-documenting" and more readable down the line (or for other developers).
Isn’t it fun to find a comment in code that’s completely out of place and useless? What if you could write fewer comments and still keep the code easy to understand? One of the primary ways to do this is making your code-self documenting. When code is self-documenting, it doesn’t need comments to explain what it does or its purpose, which is great for making the code easier to maintain. As a bonus, with fewer comments, it’s less likely they’ll be crap! In this article, I will show you several ways you can make your code document itself.
He breaks it up into a few different sections, each with some code examples and descriptions:
- Naming things
- Extract functions
- Introducing variables
- Defining class and module interfaces
- Code grouping
He finishes up with a few smaller tips including "don't use strange tricks" and "use named constants". What do you think makes for good self-documenting code? Share some of your own thoughts on the post.