Documentation

More documentation is better. Some believe that code should be self-documenting and clear on its own, and comments could be redundant or diverge from the code itself. I don’t find those arguments convincing. Redundant comments that don&rsuo;t say anything can be removed quite easily. While comments that have diverged could be an issue, the simple solution is to treat the code as the source of truth and the comments as an explanation that may or may not be applicable. By doing so, it should be easy to see that comments can only help because ignoring the comment is the same as not writing it. A refutation may be that programmers would write code that’s less clear since they can rely on the comment for clarification. Again, the solution would be to write the code as clearly as possible as if we were writing the no comment case. The divergence itself can also be helpful. We can git blame to find when the comment was first written and analyze the code at that point in time. We can then step through the git log to see how the code has diverged corresponding to the git commit messages. Figuring out code is a bit like looking through history, and every data point can be helpful.

In my more recent personal projects, I’ve been adding documentation and specs straight to my codebase as markdown files. Beyond documentation about getting the project started and deployment, I also write about the architecture, non-obvious patterns, and really just anything that would be helpful to know about the code. I’ve also created specs in markdown to keep track of what I’m working on. I like the idea of having everything in git in a plaintext-like repository and not on some proprietary service. I’m not sure if this really scales beyond my personal projects because at some point, specs would have to be worked on by non-developers.

Chess Engines and Poker Solvers

I’ve been watching a bit of chess online, and a concept that’s stuck out to me is that when top players will play different lines to get outside of basic theory and/or their opponent’s comfort zone. Players can practice these alternative lines by playing with engines. I wonder if this will be applicable at some point to poker? More players are working with solvers to create unexploitable strategies. From what I understand, the game trees are still rather complex so the strategies are typically only generated for a specific set of boards and ranges, and a specific set of bet sizes. I wonder if at some point players will use the solver with nonstandard plays, like uncommon bet sizes or slightly modified ranges, that could give the player an advantage.

Clarity of Code

I was watching the 2014 keynote at Railsconf with DHH and found myself agreeing with his points. I feel like treating code as writing was how I started out programming, but my code wasn’t that great, so I decided to try and fix that. I wanted to try and find ways to make my code bug free and objectively better. Basically, I was trying to science and engineer it by applying patterns. I definitely think that learning these patterns and ideas made me a better programmer, but similar to DHH’s thoughts, the blind application of patterns does not in and of itself make the code better.

Relatedly, I feel like there is this push to try and find objective silver bullets to programming, and while there are programs striving for a higher level of correctness, the overwhelming proof is that in practice, we have not been able to write code that’s objectively correct and bug free. The closest we may have gotten is NASA’s Power of 10 Rules.