Human Factors
SWEBOK Ch. 13 Sections 15 & 16
15 Basic User Human Factors
(I/O, error messages, and robustness)
15.1. Input and Output
15.2. Error Messages
15.3. Software Robustness
Human User Factors
Input and Output
Make input convenient
Consider default values
Consider input format
Tell the user the expected format and units of measurement for desired input, like "Enter speed as a whole number in miles per hour:", not just "Enter speed"
Validate input - check the validity of the inputs and return values before progressing further
Consider output format
Describe output, like "The area equals 45 square feet." not just "45".
Make output pleasing
All words seen by the user are spelled properly and basic grammar, such as capitalization, should be correct and current. Use a spellchecker and/or proofreader if necessary.
Error Messages
Should be friendly, clear, to the point, and timely
Exit gracefully if necessary
Software Robustness - the ability to tolerate erroneous inputs
Program shouldn't crash when a string is entered but a number was expected, for example
radius = int(input("Enter the radius: "))
If the user entered the word "ten" it could not be converted to an int and it would cause an exception.
If an exception is not handled, the program crashes.
If a line of code that causes an exception is in a try statement, the exception would cause program execution to jump to the catch or except line.
Example in Python
while True:
try:
radius = int(input("Enter the radius: "))
break
except ValueError:
print("Error. Must be a whole number.")
Other Tips
Give the user information about the program, such as a brief introduction statement.
Observe someone else using your program without giving them instruction or guidance.
Other Resources
16 Basic Developer Human Factors
(comments, structure, and readability)
16.1. Structure
16.2. Comments
Human Developer Factors: Style / Structure
Well-structured programs are easier to understand and modify.
A place of employment might have you use a certain style guide. If not, or until then, find and use a popular style guide for the language you are using, or use the style guide for a place you might like to work, like Google's Style Guide.
Most IDEs have an auto-formatter and options for changing and importing settings.
There are style checker plug-ins for many languages for many IDEs like StyleCop for C# and CheckStyle for Java.
Human Developer Factors: Comments / Documentation
Comments in code are important for many reasons.
First, there are several “real world” benefits. Programs are most often written in teams and comments can help team members understand what is happening in the code. Also, programs are often maintained long after they are written by different programmers. If you are ever in the position of having to support code someone else has written you will greatly appreciate their comments, and others will appreciate the comments you add.
Although your class assignments probably aren’t these types of programs, there are still many good reasons why you should add documentation: to establish good habits early, to enhance your assignments so they are more beneficial to you as references in future courses or on the job, to provide insight of your thinking to the instructor, and to create a quality artifact for a student portfolio.
Javadocs in Java / IntelliJ
More Information
Comments are More Important than Code ACM article
Coding Techniques and Programming Practices Comments section MSDN
Comment examples Stack Overflow, some funny, some explicit