Lesson 6 • Beginner

Comments and Documentation

10 minutes

Foundation

💬 What are Comments?

Comments are notes you add to your code to explain what it does. They're completely ignored by the computer when your program runs – they exist only for humans reading the code.

Why Comments Matter

Help others understand your code
Help YOU understand your own code when you return to it later
Explain complex logic and decisions
Document assumptions and requirements
Make teamwork easier

Comment Syntax

In iPseudo, comments start with the # symbol:

# This is a comment

Everything after # on that line is a comment and will be ignored.

Single-Line Comments

Example: Single-Line Comments

Algorithm CommentExample

# This is a full-line comment

var age = 25  # This is an inline comment

Print "Hello"  # Comments can appear after code

Endalgorithm

📖 Types of Comments

1. Explanatory Comments

Explain what the code does:

# Calculate the area of a circle
var area = 3.14159 * radius * radius

2. Clarification Comments

Explain why the code does something:

# Using 0.08 because state tax rate is 8%
var taxRate = 0.08

3. TODO Comments

Mark things to do later:

# TODO: Add input validation
var age = Input "Enter age:"

4. Section Headers

Divide code into logical sections:

# ===== GET USER INPUT =====
var name = Input "Name:"
var age = Input "Age:"

# ===== PROCESS DATA =====
var isAdult = age >= 18

# ===== DISPLAY RESULTS =====
Print name, "is an adult:", isAdult

✅ Good Commenting Practices

1. Explain the WHY, Not the WHAT

Bad Example: States the Obvious

# Add 1 to x
x = x + 1

# Print the result
Print result

Good Example: Explains Purpose

# Increment attempt counter for retry logic
x = x + 1

# Display final calculated value to user
Print result

2. Keep Comments Up-to-Date

Warning: Outdated Comments

Wrong or outdated comments are WORSE than no comments! If you change your code, update the comments too. Misleading comments waste time and cause bugs.

3. Write for Your Audience

Consider who will read your code:

Beginners: Explain more, use simple language
Experienced programmers: Focus on complex logic and design decisions
Future you: Document your thought process and assumptions

4. Use Descriptive Variable Names

Good variable names reduce the need for comments:

Needs Comments

# t is total price
var t = 100

# r is tax rate
var r = 0.08

# Calculate final amount
var f = t + (t * r)

Self-Documenting Code

var totalPrice = 100
var taxRate = 0.08
var finalAmount = totalPrice + (totalPrice * taxRate)

📋 Documentation Headers

Start your programs with a documentation header:

Example: Program Header

Algorithm StudentGradeCalculator

# =============================================
# Program: Student Grade Calculator
# Author: Your Name
# Date: October 5, 2025
# Description: Calculates final grade from
#              test scores and homework grades
# =============================================

# Program code starts here...

Endalgorithm

Complete Example

Well-Commented Program

Algorithm TemperatureConverter

# =============================================
# Temperature Converter (Celsius to Fahrenheit)
# Converts temperature using: F = C × 9/5 + 32
# =============================================

# Get temperature input from user
Print "=== Temperature Converter ==="
var celsius = Input "Enter temperature in Celsius:"

# Convert to Fahrenheit using standard formula
# Formula: F = C × 9/5 + 32
var fahrenheit = celsius * 9 / 5 + 32

# Display both temperatures for comparison
Print ""
Print "Temperature Conversion:"
Print celsius, "°C =", fahrenheit, "°F"

# Provide context for common temperatures
Print ""
Print "Reference: Water freezes at 0°C (32°F)"
Print "Reference: Water boils at 100°C (212°F)"

Endalgorithm

❌ What NOT to Comment

1. Obvious Code

# Bad: This is obvious
x = 5  # Set x to 5

2. Bad Code (Fix it instead!)

# Bad: This is a hack, needs fixing
result = value * 1.0000001  # Don't ask why

3. Every Single Line

Too many comments make code harder to read:

# Bad: Over-commented
var x = 5  # declare x
var y = 10  # declare y
var sum = x + y  # add them
Print sum  # print result

Professional Tips

The Golden Rule

"Code tells you HOW, comments tell you WHY."

Good code is self-explanatory for the "how". Use comments to explain:

Why you chose this approach
What problem you're solving
Any non-obvious requirements or constraints
Complex algorithms or business logic

Comment Levels

Use different comment styles for different purposes:

# ===== MAJOR SECTION =====

# Subsection description

var x = 5  # Inline note about this line

🎓 Real-World Example

Example: Well-Documented Grade Calculator

Algorithm FinalGradeCalculator

# =============================================
# Final Grade Calculator
# Calculates weighted average from assignments
# Weights: Tests 50%, Homework 30%, Final 20%
# =============================================

Print "=== Grade Calculator ==="
Print ""

# ===== GET SCORES =====
# Get individual component scores from user
var testAverage = Input "Enter test average (0-100):"
var homeworkAverage = Input "Enter homework average (0-100):"
var finalExam = Input "Enter final exam score (0-100):"

# ===== CALCULATE WEIGHTED GRADE =====
# Using school's official weighting policy:
# - Tests contribute 50% of final grade
# - Homework contributes 30% of final grade
# - Final exam contributes 20% of final grade

var testWeight = 0.50
var homeworkWeight = 0.30
var finalWeight = 0.20

# Calculate weighted components
var testContribution = testAverage * testWeight
var homeworkContribution = homeworkAverage * homeworkWeight
var finalContribution = finalExam * finalWeight

# Sum all weighted components for final grade
var finalGrade = testContribution + homeworkContribution + finalContribution

# ===== DISPLAY RESULTS =====
Print ""
Print "=== GRADE BREAKDOWN ==="
Print "Tests (50%):", testAverage
Print "Homework (30%):", homeworkAverage
Print "Final Exam (20%):", finalExam
Print "------------------------"
Print "FINAL GRADE:", finalGrade

# Provide letter grade interpretation
Print ""
Print "Grade Scale: A(90+), B(80-89), C(70-79), D(60-69), F(<60)"

Endalgorithm

📋 Quick Reference

Comment Type	When to Use	Example
Explanatory	Explain what code does	`# Calculate total price`
Clarification	Explain why you did something	`# Using 8% based on state law`
TODO	Mark future improvements	`# TODO: Add error handling`
Section Header	Divide code into sections	`# ===== CALCULATIONS =====`

Key Takeaways

✅ Comments start with # and are ignored by the program
✅ Explain WHY, not WHAT (code shows what)
✅ Use comments to document complex logic and decisions
✅ Keep comments up-to-date when code changes
✅ Use descriptive names to reduce need for comments
✅ Add program headers to describe overall purpose
✅ Don't over-comment obvious code

💪 Practice Exercises

Try These Exercises

Exercise 1: Add Comments

Take one of your previous programs and add appropriate comments: header, sections, and explanations.

Exercise 2: Improve Comments

Find code with bad comments (obvious or outdated) and rewrite them to be more useful.

Exercise 3: Documentation Header

Create a new program with a complete documentation header including purpose, author, date, and description.

Beginner Level Complete!

Congratulations! You've completed the beginner lessons and learned the foundations of iPseudo. You're now ready for intermediate topics! In the next lesson, we'll learn about conditional statements to make decisions in your programs.