Improve code documentation

[ozgunbabur]

Please revise the code to make sure

• There is a space between each logical block
• Each logical block is associated with a comment that describes what is aimed with that block

Don't try to write concise code. Prioritize readability and comprehensibility.

[AdamFinkleUMB]

What do you mean by code block? I have added a docstring to every function and comments to every freestanding block of code, but a code block is strictly as small as a single if-statement.

[ozgunbabur]

The docstrings are very nice. This is one part of the documentation. The other part is adding comments in the code, describing what you are doing, line-by-line. Imagine you are pulling up that code in a presentation and you want your audience to understand what the code does. What would you tell them? Write these in the code. Ideally, the amount of those explanations should take a similar amount of space as the code.

[AdamFinkleUMB]

Functions, classes, and modules with clearly documented inputs and outputs and an abstract description of their inner-workings, themselves written clearly enough to be read and understood by anyone who knows Python and the domain, would remain accurately documented even when re-factored or modified. I will organize and document the codebase accordingly.

While a few in-line comments can clarify highly-technical code, relying on them to understand exactly how a program works leads to madness, for what we learn from comments is at best our interpretation of someone's interpretation of how that program works, and any standard of comments rigorous enough to exactly specify the behavior of a program would inherently be rigorous as the language of that program--entailing comments for those comments, and so on. Moreover, whenever the code and comments would disagree, we would have to decide whether the comments were inaccurate and to change them to reflect the code as it is, or the code were incorrect and to change it to do what the comments would say it does.

[AdamFinkleUMB]

I have refactored the code base to have about a paragraph of docstring for every paragraph to a line of code. Do we need more documentation?