3 ms·
My best notes for code clarity is to be in the frame of mind of the next person reading this that begins with no context. To that end it's best to let code read
by karmakaze 6y ago
My best notes for code clarity is to be in the frame of mind of the next person reading this that begins with no context. To that end it's best to let code read well from the top and at each level like good prose, with only as many words as the the importance of the parts.
Apply the "Principle of least astonishment" aggressively in all aspects, variable/function/argument/class naming, arguments/mutation, return type variations. Make it so reading the call site of the function lets the reader accurately guess what it does and not need to look into how it does it, or if it does something else too/sometimes.
All of that is useful but doesn't help if the overall structure of decomposition from top to bottom is poorly chosen: reflect and reconsider. "Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away."