Explicit block & code folding for better communicating your thoughts
It happens that we end up writing long methods with a lot of lines, and even break lines and comments are not enough to reason about the code.
The best practice (or is it?) is often to extract related statements into smaller functions and calling them into the original one.
- The issue with this approach (especially in a collaborative environment) is that functions are often meant to be re-used, but it might not be what you want in that case.
- Another weakness of factoring the code into smaller functions, where we know all of them are going to be called one after the other, is that we will have to navigate back and forth between their definitions and the main method where they are called.
- These statements are logically related (similar to a function)
- This group is meant to be used here only and nowhere else (as opposed to functions)
Code folding & Comments
Add a succinct comment just before the block and see at glance what the purpose of the block is (you could even add keywords if that can help).
Now fold everything at block level: you now have a very descriptive overview of the whole flow of the method. You can now expand only the block that you need.
Using this technique will save your teammates a lot of time (and headaches) as they will have a clear summary of the method and will only have to read the code they are concerned about.
Let me know if that technique helps. Suggestions and critiques are most welcome.