[Tutor] How to refactor a simple, straightforward script into a "proper" program?

[DL Neil]

On 5/01/20 12:05 PM, boB Stepp wrote:
> On first reading, the bulk of your comments are about code
> documentation, and, I believe, expose weaknesses in my understanding
> of what is expected and required.  After I complete this initial
> reaction to your comments, I am going to hit the 'Net and review
> docstrings and code commenting and then return with some code updates
> to see if my understanding has improved.  One thing that struck me on
> my initial read is that while I was trying to refactor the original
> simple script into something more robust, I was still retaining a
> "simple script" mentality for my code documentation.  I expect this is
> a faulty habit I have fallen into from not having any oversight of my
> coding efforts (Other than my questions on this list.).

Hopefully the readings will answer that level of your question.

+1 to the mind-set of "simple-script" being incorrect, even, unprofessional.

When you think about it every function/method should be "simple"! If 
this is not immediately-apparent, recommend adding to your DRY-intent a 
paper/page or two about the principles of "successive refinement" and 
"separation of concerns".

If you take the principle of "re-use" (not quite to the point of 
absurdity), is there much of a concept of a "simple script mentality"?


+1 your attitude to improving/re-factoring code, towards improvement.

If you do not consider OOP to be (too) 'advanced', what may help is 
drawing a UML diagram - if UML is not in your portfolio (and to ease 
email-presentation), instead make two (equivalent to UML) lists:-

What is the subject of the computation? A book.
How are you measuring its size? Nr Pages.

What is the objective of the computation: set a reading-rate in pages 
per day. (more/better expression?)


List 1: what pieces of data do you need to know, to describe the book, 
and carry-out computation


List 2: what computations do you need to carry-out (in relation to the 
book), eg can we have a book with a non-positive number of pages? with a 
'number' of pages (in book, or read) which is non-numeric?


Does this process help to 'refine' the problem into smaller problems?
Does it help to organise the data?
Does it help to see what you might need to code as functions/methods?


NB it doesn't really matter which way-around you write the lists, and 
in-truth you may find that writing one stimulates additions/alterations 
to what you've already written on the other.

NBB some will argue about whether considerations of the number of pages 
in a book belong with "book" or are better tackled as 'input', but for 
this particular/introductory/illustrative thought-process it will not 
matter...


After such an exercise, does it (combined with earlier comments about 
functionality) help your thinking towards program design?


> One question I do wish to ask up front:  _If_ type annotations are
> used, does this affect how the code is documented?  My impression is
> that with my code as is (no type annotations) I should have added a
> section for each function explaining the expected type and function of
> each parameter and value returned.  But if I do use type annotations,
> that would seem redundant.

One of my favorite comments about comments (and docstrings) was 
"mumbling". My recollection is that this was describing comments that 
were either of no real use, eg "# adding a to b"; or were purely there 
in order to satisfy 'requirements' - I've been known to persuade a 
linter to shut-up by writing ''' Docstring. ''' (don't forget the u/case 
nor the final punctuation!) BTW I think I'm fooling the linter, but I'm 
really only fooling myself...


Others have recommended improved names (and the above design-exercise 
may also help with that). If a name is 'good', it requires no comment:

	number_of_pages	# book size in pages	<<<--- mumbling!

That said, does that name refer to the number of pages in the book - 
what about the number of pages the reader has already consumed?

Stating the data-type is useful. As you've already noted, the ratio of 
remaining pages must be computed with numeric values, whereas the input 
data was strings! Having this information presented as 
typing-annotations saves us from putting it in a comment.
(which is 'better' is another discussion, for another day)


That said, for your consideration:
(with apologies that email will re-format/mess-up presentation)

	function calculate_remaining_pages(
			number_of_pages_in_book:int,
			number_of_pages_already_read:int,
			)->int:
		return ( number_of_pages_in_book -
					( number_of_pages_in_book -
					number_of_pages_already_read
					)
			)

With the choice of reasonable (if improvable - in your application) 
names, and very simple functionality, what could be added through 
'documentation'?


However, consider a function which had the objective of accepting 
("only") a single numeric input value. Could you (anyone) write a 
function/method which required no supportive documentation?


So, in the same way that functions/methods written in Python describe 
functionality, what is the purpose of 'documentation'?
(and for bonus-points: who is documentation written to/for?)
-- 
Regards =dn