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.")

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.

  • Style in Python / PyCharm

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.

  • Docstrings in Python / PyCharm

  • Javadocs in Java / IntelliJ

  • More Information