How Simple Commenting Rules Improve Code Structure

In my last post I described my rules for commenting code.

Here I am going to talk about how following those rules makes your code better.

The statement is slightly backwards. What I am really saying is that if you can legitimately describe your code using the commenting structure I describe your code will be better than if you can't.

In particular: If you can accurately and completely describe a function with one simple statement (with no, ifs, ands, or buts) that function is much more likely to belong to a well designed system than if you can't.

The bad news is that you have to design the system and write the comments before you can apply the test to see if the system is well designed. The good news is that is relatively early in the system development.

This is not the holy grail of a rule that will allow for the mechanical generation of high quality designs. It is an after the fact test that should indicate design quality, which is, I think, as good as we are going to get.