> If you are able to just use names and types to document your intentions, pitfalls etc ... then by all means, do just this That's sort of the point. Step 1, y

> If you are able to just use names and types to document your intentions, pitfalls etc ... then by all means, do just this That's sort of the point. Step 1, your code should be self explanatory. When the natural interpretation a reasonable person would have from reading the code differs from reality: that's when you add Step 2: add comments to "fix" the gap between perception and reality. The less Step 2 is necessary the better.