I saw something mythical yesterday; something I hadn’t actually seen before. I saw self documenting code. This is unique in my experience.
I have seen on many occasions, code described as self documenting but which was anything but. I suspect a big contribution to the self documenting nature of the code is that it mapped a relatively simple process. The logic was straightforward. The objects were straightforward and non-complex. The code ran to 300 lines which is not a lot for a full application, and the application was culturally common. It was written in Python. It was a thing of absolute beauty.
I’m a fan – in general – of providing code comments, particularly in the zone of Why rather than How. My experience is that the why tends to get forgotten, that current knowledge gets taken for granted and that if the code base is still in use in 10 years time, you probably can’t rely on current knowledge.
In particular I am a fan of assuming that you should make your code as easy to read for the next person as possible. Ultimately, you shouldn’t assume – as a lot of programmers seem to do – that because you approach a problem in a specific way, that everyone will, and that everyone will immediately understand your approach.
And especially, if you’re not writing a clone of a well loved arcade game, it’s probably a good idea not to assume that your code will self document. What’s rare is wonderful and seriously, I have never – before yesterday – seen a piece of code longer than about 5 lines that could justifiably be called self documenting.
What’s rare is wonderful.