Self-Documenting Code Is an Illusion

22 December 2021 by Phillip Johnston • Last updated 18 February 2025Many people claim that documentation is a waste. According to this view, code should be “self-documenting” so that we eliminate the need to have documentation and comments. The sole focus on self-documenting code ignores the fact that it is harder to read code than it is to write it, and this is true even for code that you wrote in the past! Recreating a model of the intended system behaviors from source code is also a difficult, time consuming, and error prone process. The other problem is that code …

Continue reading “Self-Documenting Code Is an Illusion”