There are some problems with this program, but is does work. A large problem is that it always choses the same number every time it is executed (that number is 7). We will fix this issue later on. A less critical problem is that the program is undocumented; that is, there are no instructions to a player concerning how to use the program, and there is no description of how the program works that another programmer might use if modifying this code. This can be fixed by providing internal and external documentation.
External documentation is like a manual for the user. Most programs have such a thing, and even though this program is quite simple, some degree of documentation can be provided. In fact, it is brief enough that it could be printed whenever the program starts to run.
print (“Pick-a-number is a simple guessing game. The”)
print (“computer will select a number between 1 and 10”).
print (“and you are expected to guess what it is.”)
print (“When the program displays ‘Please guess”)
print (“a number between 1 and 10: ‘ you type in”)
print (“your guess followed by the <enter> key. Your “)
print (“guess must be an integer in the range 1 to 10.”)
print (“The computer will tell you if you win or lose.)
For many more sophisticated programs, such as PowerPoint, the documentation is many pages and forms a small book. It is distributed as a booklet along with the software or provided as a website.
Internal documentation is intended for programmers who have access to the source code of the program. It can take the form of written documents, too, but is commonly a set of comments that appears along with the code itself. High-level languages like Python allow the programmer to add human language text to the code that will be completely ignored by the computer, but that can be read by anyone looking at the code. These comments describe the action of the program, the meaning of the variables, details of computational methods used, and many other items of interest.
A comment begins with the character # and ends at the end of the line.
There are no rules for what can appear typed in a comment, but there are some guidelines developed through years of programming practice. A comment should not simply repeat what appears in the code, a comment explain an aspect of the program that might not be clear to a person looking at it, and it should be written in plain language. As an example, here is the guess-a-number program with comments included:
# This program selects a number between 1 and
# 10 and allows a user (player) to guess what
# it is.
choice = 7 # The number selected by the computer
# Prompt the user, indicating what is expected
print (“Please guess a number between 1 and 10: “)
# Read the player’s input from the keyboard
playerchoice = int(input()) # convert from string
# Print the outcome of the game.
if choice == playerchoice: # Is the player’s guess
print (“You win!”) # correct? Player wins!
else: # Otherwise the computer wins
print (“Sorry, you lose.”)
All programs should be documented as they are being written because relatively few programs are written all in one sitting. The comments in the code serve as reminders to the programmer about what the variables represent and why particular code segments read the way they do. It also indicates the current state of thinking about the design of the code. When the program is looked at again at the beginning of a new working (or school) day, the comments can be essential in resuming the work.
There is also something called a docstring that seems to do the same things as a comment, but covers multiple lines and is not really a comment. A docstring begins and ends with a triple quote:
print (“This code will execute”)
II II II
print (“This code is within a docstring”)
II II II
A docstring is actually a string, not a comment, but behaves like a comment and can be used in that way. It can be especially useful for temporarily commenting out small sections of code while trying to find out where errors are. There are also programs that collect the docstrings into a separate document that can be used as a description of the program. Their intended use is to allow the programmer to explain the purpose of certain sections of code.
Source: Parker James R. (2021), Python: An Introduction to Programming, Mercury Learning and Information; Second edition.