Re: Uses single algorithm for side-position spacing. (issue 6827072)

[dak]

To make it short: a function needs documentation that tells its purpose
in the overall scheme of things (for what purpose is it used), its
outline (what does it do), its input and output.

A "policy" may describe how they are formatted and whether or not they
are used as Scheme documentation strings.

But whether or not there is "policy", this information _must_ be present
or the function is incomplete.  That's not "policy" but "sanity".

As long as you don't have an argument better than "I never did that" or
"other code does not do that", there is _no_ point in refusing to add
this information.  In what respect will the code be better maintainable
if you omit this information?

If you have had a coherent design in mind when writing the code, it
should be fresh in your memory and it is just a matter of writing it
down.  If you did not have a coherent design in mind when writing the
code, maybe you'll even discover something dishy when trying to describe
the design.

So again: in what respect is the code improved by you not writing down
what it is supposed to achieve in what context by doing what and how?

http://codereview.appspot.com/6827072/