Documentation Outside of the Code

In professional development this is not just useful, it is obligatory. Where I am with my relatively small programs it is just starting to be useful. Commenting in the code is good and useful, but sometimes it isn't enough. This proved true with the Historical database, especially when going through the testing. A simple text file holding my thoughts and ideas about the database proved sufficient. A sample few lines from that text file:

View - Done; all options for sorting tested, and also tested viewing individuals, both with and without weblinks
Search tested - problem if no results found it still creates table and asks for which record to view. Now corrected with if searchdump: to check if searchdump is empty
New Record tested (Martin Luther)
When updating record, if no number is selected (for which record) it throws an error. Just hitting return should return to main menu. - Now corrected
When adding weblink, confirmation needed for which person is selected before adding weblink - Fixed!
Modify searching births and deaths to allow range of years to be searched - maybe leave to version 5
When trying to update record for a character's roles, I can select a role but when I enter the new role it throws an error.
 Traceback (most recent call last):
  File "C:\Users\pc\Documents\Programming\historical_4.py", line 362, in <module>
    updaterecord()
  File "C:\Users\pc\Documents\Programming\historical_4.py", line 303, in updaterecord
    oldvalue = roledump[colcount-5][0]
IndexError: list index out of range
>>>
>>> conn = sqlite3.connect("C:\sqlite\db\history1.db")
>>> curs = conn.cursor()
>>> curs.execute("SELECT Role FROM roles WHERE Name ='Mickey Mouse';")
<sqlite3.Cursor object at 0x03C32EE0>
>>> roledump = curs.fetchall()
>>> print(str(roledump))
[('Cartoon Character',), ('Entertainer',)]
>>> Fixed now.
When Updating a record and user changes the name, the subtables are not updated - i.e. the subtables use the old name and are no longer associated with that record
Fixed by inserting the following code just before the COMMIT
    if colchoice == 0:
        executable_role = "UPDATE roles SET Name = "+ newvalue +" WHERE Name = '" + updatename + "';"
        print(executable_role)
        curs.execute(executable_role)
        executable_link = "UPDATE weblinks SET Name = "+ newvalue +" WHERE Name = '"+ updatename + "'";
        print(executable_link)
        curs.execute(executable_link)
Deleting link - at the moment it relies on there being only a few entries in the table - it prints out all links for all names. This may need to change when more links are added, so that the user selects the historical name first then which link associated with that name to delete.  Probably leave until version 5

I've adjusted the fonts to clarify what's what. When testing, I will encounter either problems or possible improvements. Jotting them down in this text file gives me a to-do list, which I can cross off as I address each problem.
From a professional perspective this is not very neat or well-structured. At the moment it doesn't have to be - it is purely for my own reference, there are no work colleagues or fellow developers who need to understand what's going on. Nonetheless, it is a start of what could be a very sensible habit.

Comments and Readability

Most folks who deal with computers would agree that the top priority for a computer program is that the computer can run it. I think of this as computer readability. If the Python interpreter can't read a program, it won't run and will throw an error, usually a syntax error.

In the past I have assumed this is the be-all and end-all of readability - as long as Python understands the program nothing else needs to understand the program. As I am not yet a professional programmer, so far (until I started this blog) I was the only one who had to read the programs I wrote.

Problems arose when I had written a program that was either quite complicated (at least by my standards) or involved something new that I had recently discovered in a textbook or web forum. I would be okay writing it (maybe after some trial, error and debugging) and while this process was going on I would be aware of the concepts I was trying to implement.
But if I came back to the program a week or a month later and looked at what I had done, the techniques, structures and functions I had been juggling in my head had by then faded away. I had to look at my code and work out what I had done.
Even if nobody else was looking at my code, I realised that human readability was useful for my own understanding of my own programs. I have borrowed a number of techniques that have helped me with my own programs and I hope will allow others to follow my coding more easily.

• Don't be afraid to comment as often as you want to. Although different programmers will have different ideas of how much comment is appropriate there have been a few of my programs where there has been more comment than Python-readable code. Some may say that's too much, but if I'm the only one reading the code, then it's up to me. 
• As I have become more familiar (fluent?) with Python, there are a number of basic expressions that I don't need to comment on - I am more likely to use comments on or around lines that I might struggle with. I may also comment on the bigger picture of how different parts of the program hang together, particularly when it is not obvious from the code itself. Sometimes the comments are not so much what I am doing in the code so much as why I am doing it. 
• Appropriate and descriptive names. Currently the main names I have used on this blog are variables, though later on there will be functions and classes that the programmer gives names to. Although typing out long names is a bit more tiresome than short ones (and there is an increased chance of spelling errors), being given a clue what the name represents makes programming a lot clearer for me and makes logical errors less likely. In professional circles this is known as self-documenting code. Of course, it's sensible not to have names too long (whether variable, function or class) and if you want you can keep it short and sweet, with a comment at the start or when the name is defined/initialised to explain what it is. 
• If a line of code starts looking so long, complicated and convoluted I am no longer sure what it means, I will try to split it up into two or more simpler lines. If that means I have to create a new variable to pass a value on from one line to another, so be it. I know some programmers try to get as much code onto a single line as possible, with expressions nested inside other expressions. That's okay up to a point. But it becomes like a sentence in English that is a paragraph long, full of phrases, conjunctions, transitions and structures. It's easier just to add a few full stops and split it into shorter sentences. 
• Superfluous and unnecessary code should be eliminated. I have sometimes used the comment hash # to temporarily disable lines of code while I am debugging or experimenting. This is fine in the short term, but when I have decided that line really shouldn't be there I delete it rather than leave it there hashed out. Similarly if possible I will implement things directly rather than in a round-about way, keeping it to as few lines as feasible (while bearing in mind the point above this one). 

In companies and organisations where code is shared and maintained by lots of people, readability becomes very important. Although I have not yet needed to deal with the matter directly, I have heard that companies often have their own style guides saying how code should be made readable in a consistent way.

A lot of programmers using other languages will say that indentation is important for human readability. As we have seen, in Python it is necessary for computer readability - your program won't work (or at least not as expected) if you don't get indentation right according to the Python interpreter. This has the effect (I'm sure it is intentional) of making Python code easier to read.