The longer I do this job, the less I value extremely high intelligence. In the end whatever you work on has to be able to be picked up by someone else, so unless you're working in very specific fields, there's not a lot to be gained by being extra clever. Consistency is a lot more valuable. As you said, being able to reason about a system is incredibly important. That can be accomplished in a lot of ways, but the _best_ ways I have found over the years are:
- Document everything, and have a system for keeping documentation up-to-date (stale documentation is often worse than no documentation at all). Often it's possible to include a README.md in the same folder as the code it is talking about. You can link to it from a parent directory to keep things discoverable.
- Have a test suite for anything you need to be able to reason about. Also, design your test suite so that it defines your application's behavior with positive assertions (i.e. when <condition> then <result>)
- Focus on solving a "class" of problem and document over-arching solutions. E.g. littering your codebase with a bunch of one-off optimizations may improve your application's performance, but the goal should be to have a consistent way of building the application so that these improvements are essentially a free by-product. For instance, in a data-heavy environment you may want to write some abstractions around bulk insertion and paging that can be applied universally. This way of problem-solving leads to good consistency and less cognitive load, because rather than a giant block that I look at and think, "What is this thing? oh, that's a paging implementation, gross!" I can instead recognize almost immediately what this thing is ("Oh, this is paged using PagedQuery, cool!") and also have other examples of its use around the codebase I can pull from to do whatever it is I'm actually trying to get done.
- Document everything, and have a system for keeping documentation up-to-date (stale documentation is often worse than no documentation at all). Often it's possible to include a README.md in the same folder as the code it is talking about. You can link to it from a parent directory to keep things discoverable.
- Have a test suite for anything you need to be able to reason about. Also, design your test suite so that it defines your application's behavior with positive assertions (i.e. when <condition> then <result>)
- Focus on solving a "class" of problem and document over-arching solutions. E.g. littering your codebase with a bunch of one-off optimizations may improve your application's performance, but the goal should be to have a consistent way of building the application so that these improvements are essentially a free by-product. For instance, in a data-heavy environment you may want to write some abstractions around bulk insertion and paging that can be applied universally. This way of problem-solving leads to good consistency and less cognitive load, because rather than a giant block that I look at and think, "What is this thing? oh, that's a paging implementation, gross!" I can instead recognize almost immediately what this thing is ("Oh, this is paged using PagedQuery, cool!") and also have other examples of its use around the codebase I can pull from to do whatever it is I'm actually trying to get done.