Documentation

Learning Objectives Define what code documentation is and explain its importance for collaboration and maintenance. Identify and correctly use single-line and multi-line comments in a programming language. Write effective comments for variables, functions, and complex code blocks. Differentiate between helpful and unhelpful (redundant or vague) comments. Explain the concept of self-documenting code through clear naming conventions. Describe the purpose of a high-level README file for a project. Ever tried to read someone else's messy handwriting or follow a recipe with missing steps? 🗺️ Code without notes is just like that, a puzzle without a guide! In this lesson, you'll learn how to leave clear, helpful notes inside your code. This practice, called documentation...

TermDefinitionExample DocumentationThe practice of adding explanatory notes and materials to your code. It's the human-readable information that helps people understand, use, and modify the software.This includes comments inside the code, a README file for the project, and guides on how to use a program. CommentA programmer-readable note directly inside the source code. The computer ignores comments when running the program.In Python: `# This line calculates the user's final score.` Single-Line CommentA comment that takes up only one line. It's typically used for short, quick explanations of a specific line of code.In Python, it starts with a `#`. For example: `player_score = 100 # Set initial score` Multi-Line Comment (Block Comment)A comment that can span across multiple...

Single-Line Comment Syntax In Python: `# text` In JavaScript/Java/C++: `// text` Use this for brief notes on a single line. Place it above the line it refers to, or at the end of the line if it's very short. Multi-Line Comment Syntax In Python: `""" line 1 line 2 """` In JavaScript/Java/C++: `/* line 1 line 2 */` Use this for longer explanations that won't fit on one line. In Python, this is often used for 'docstrings' at the start of a function. The 'Why, Not What' Rule Good comments explain the *purpose* or *reasoning* behind the code, not just what the code is literally doing. Avoid restating the code. Instead of `# Add 1 to score`, write `# Add bonus point for completing the level`.