© Michael Stueben 2018
Michael StuebenGood Habits for Great Codinghttps://doi.org/10.1007/978-1-4842-3459-4_8

8. Comments

Michael Stueben1 
(1)
Falls Church, Virginia, USA
 

Use comments with care. The 5-line Boolean function below is my revision of 13 lines of code with nine more comment lines. The longer version was an Internet instructor’s example, with the direction to comment nearly every line of code (terrible idea, even for beginners). Self-documentation is better.

def isAllVowels(stng):
    for ch in stng.lower():
        if ch not in ['a', 'e', 'i', 'o', 'u']:
           return False
    return True
Self-documenting code eliminates the need for many comments. But we still need comments for the following reasons:
  1. a.

    to show organization (break ...

Get Good Habits for Great Coding: Improving Programming Skills with Examples in Python now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.