As I continue working on projects of my own, as well as those in my day job, I am learning more about the best ways to use AI to create software. Mostly Claude and sometimes Codex. One thing I cannot help noticing is the sheer number of comments AI adds to the code. In January 2025, I wrote a blog post called Comments in Code: Just Don’t Do It , in which I quoted Uncle Bob: It is well known that I prefer code that has few comments. I code by the principle that good code does not require many comments. Indeed, I have often suggested that every comment represents a failure to make the code self explanatory. I have advised programmers to consider comments as a last resort. I went on to say: Comments should always be “why”, never “what”, and only when absolutely necessary. If you feel the need to write a “what” comment, put the code in a well-named, meaning descriptive, function instead. I stand by this view. Comments should be few and far between and,...
In my previous post, The Elements of Programming Style: still worth reading , I argued that the book is still worth reading. Going back through the rules made me think about which ones I would give to a developer today. Most need no help. Clear names, small modules, testing boundary values and measuring before optimising are as useful now as they were when Brian Kernighan and P. J. Plauger wrote the book. A few rules, though, speak in the syntax of Fortran and PL/I. Fortran is still used in scientific and high-performance computing, but many developers won’t recognise an arithmetic IF or a DATA statement. In those cases, I’ve kept the original rule and written a version that carries its advice into other languages. These are the 72 rules I took from my reading notes, in order. Where I’ve changed one, I’ve included the original, the updated rule and my reason. 1. Write clearly - Don’t be too clever 2. Say what you mean, simply and directly. 3. Use library functions. 4. Use temporary var...