Overview

You’ve named a lot of variables, functions, and classes in your time, probably some better than others. Today we’re diving into how to think about names and comments so that your code is as clear as possible, and maybe even ‘self-documenting’.

Basic Learning Objectives

Before class, you should be able to:

  • Define “self-documenting code”
  • Give examples of acceptable and less-acceptable names for functions
  • Give an example of a good use of context in variable naming

Advanced Learning Objectives

After class, you should be able to:

  • Use the best practices in variable, function, and class naming, and explain how these can be used as a part of producing self-documenting code.
  • Explain, and utilize, best practices in commenting code.

Readings

To achieve the basic learning objectives, read the following in Clean Code:

  • Chapter 2, “Names”. You can skip the section “Avoid Hungarian Codings.”
  • Chapter 4, “Comments”

Checks

Look through (some of) your group’s project code and see what examples or anti-examples you can find for the different naming and commenting principles. Take note of them to discuss with your team in class.