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

[David L Neil]

On 6/01/20 1:29 PM, Alan Gauld via Tutor wrote:
> On 05/01/2020 02:06, DL Neil via Tutor wrote:
> 
>> 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...
> 
> I once worked on a large (very large - 10,000+ files) C project.
> It was initially written by a US tech company and sent to us.
> They in turn had employed many short term contractors to meet
> the project deadline...
> When we reviewed the code we found lots of files with things
> like this at the top:
> 
> /* Scooby dooby dooo.....
> 
> <insert 50 blank lines...>
> 
> Where are you.... */
> 
> Or
> 
> /* I need comments to pass the metrics program....
> 
> 
> <followed by the lyrics of a popular song.>
> 
> My favourite was "I did it my way..."
> but another apropos title was the chorus of
> "The Marvellous Toy"  :-)


Way back, in the 80s(?), I had a salesman trying to sell me one of those 
'measure the performance of your programmers'-type products. Even he 
admitted that we could expect just such behavior!
(I think it also flagged goto-statements as 'red flags'!)


Classic example of 'the law of unintended consequences'! If you make an 
(artificial/boorish/stupid/...) rule, people feel forced to obey the 
'letter of the law' but 'miss' (either deliberately or ignorantly) 'the 
spirit of the law'.

My favorite of these was during one of my UN assignments to a country I 
shall not name (to protect the 'innocent'). These folk had a 
laissez-faire culture and thus attitude to 9-5 work-hours. A pair of 
colleagues from India/Sri-Lanka, whose culture is quite different and 
whose attitude to such poor time-keeping was one of major criticism, if 
not anger; decided, without discussion amongst the team or with many of 
our host management, to install time-card machines. They were amazed to 
read the first monthly-report and find that one department's personnel 
almost all arrived for work something like 90-minutes before 'time' - 
and that they all left within minutes (again, usually 'over' time). 
Casual observation showed that this was not reality. It took them ages 
to work-out how it was done - which showed another cultural-gap in 
group-dynamics, and attitudes to 'team-work'!

BTW lest anyone think I was criticising any one race/creed/culture, let 
me say that one of my first meetings in London a short-time later, 
featured me waiting well beyond the 1000 appointment-time, whilst my 
'host' completed reading his morning newspaper... I don't think a 
time-card would have solved his problem - nor improved his documentation!


In partial response to a couple of comments made earlier in this thread:
these days we don't need to comment-out chunks of code (per Scooby Doo, 
above) when we are refactoring/replacing it - we have VCS enabling us to 
revert to version n-1, or to run a compare-analysis if/when required!

For similar reasons, many of the web-articles talking about the various 
comments we can/should/must add to the beginning of our program(me)s 
have become anachronistic, eg we used to keep notes of how the code had 
been changed, release by release (per Release Notes, but on a 
module/class basis). No longer necessary because those comments should 
document each VCS-commit! Similarly, the version numbering system comes 
from delivering a repository's 'latest version' to the 'delivery 
mechanism'(s).

-- 
Regards =dn