in reply to Re: Re (tilly) 2: Maintainable code is the best code
in thread Maintainable code is the best code

I believe I understood what was said, but I may not have understood it like you wanted me to.

My point is this. Saying "minimal" indicates that one should not view verbose commenting as a way to turn bad code into maintainable code. Saying "sufficient" bears no such implication. Cutting loose with volumious comments is sufficient but not minimal.

Hopefully we find ourselves in agreement on what kind of code is best for maintainability. However one we are in agreement on that, then the question is what kind of statements will lead people to that end. My contention is that it is better if you say minimal. First that statement already makes it clear that there are are things which cannot reasonably said with clear variable naming. Second it makes it clearer that comments do not substitute for what can be said through good naming. And finally it makes the point that while further things need to be said, it is is a maintainability issue to say them at too much length.

Saying sufficient communicates more strongly that there are things that cannot be said through good naming which need to be said through comments. But it does not stress that commenting can be overdone, and does not indicate to what extent comments don't replace naming.

Now which message is more important to get across clearly depends on what your audience is. However it is my belief that the message indicated by "minimal" is more likely to be applicable to the random PerlMonk than the message indicated by "sufficient". Perhaps a better phrase is something like, With minimal comments that are sufficient to the cause...

  • Comment on Re (tilly) 4: Maintainable code is the best code