Welcome to Coding Standards!
In this chapter, we are going to learn how to write code that isn't just "correct" for the computer, but "clear" for humans. Think of coding like writing a story: even if the grammar is perfect, it won't be a good book if it's messy and hard to read. By following Coding Standards, you ensure that your work is professional, easy to fix, and easy for others to understand. Don't worry if it seems like a lot of "rules" at first—most of these will become second nature as you practice!
1. Indentation and White Space
White space refers to any part of your code that is "empty," such as blank lines or spaces between operators. Indentation is the specific use of spaces at the beginning of a line to show which "block" of code a statement belongs to.
Why is it important?
In many languages, indentation is just for looks. But in Python (the language used in H2 Computing), indentation is mandatory. It tells the computer which lines belong inside an if-statement, a loop, or a function. Beyond the rules, using white space helps your code "breathe," making it much easier for your eyes to scan.
How to use it:
1. Standard Indentation: Use exactly 4 spaces for every level of indentation.
2. Logical Gaps: Put a blank line between different sections of your code, such as between two different functions.
3. Operator Breathing Room: Instead of writing x=y+5, write x = y + 5. It is much easier to read!
Analogy: Think of indentation like the "bullet points" in a list. The sub-points are tucked under the main point to show they are related. Without that tucking, everything just looks like one big, confusing pile of text.
Quick Review:
- Indentation: Shows the structure of the logic.
- White Space: Helps separate different ideas visually.
2. Naming Conventions (Identifiers)
An identifier is simply a name you give to something in your program, like a variable, a function, or a class. Choosing "good" names is one of the most important habits of a great programmer.
The "Official" Rules (from the Syllabus Reference Guide):
- Names must start with a letter (a-z, A-Z) or an underscore (_).
- They can be followed by letters, numbers, or underscores.
- Reserved words (like if, while, def) cannot be used as names.
- Names are case-sensitive (myScore is different from myscore).
Meaningful Names:
Always use meaningful identifier names. Avoid using single letters like x or y unless you are doing a very simple math calculation.
Bad: a = 3.14 * r * r (What is 'a'?)
Good: area = 3.14 * radius * radius (Much clearer!)
Common Styles:
- snake_case: Words are all lowercase and joined by underscores (e.g., student_name). This is the standard for Python variables.
- camelCase: The first letter is lowercase, and each following word starts with a capital (e.g., studentName).
Common Mistake to Avoid: Don't make names *too* long. the_variable_that_stores_the_user_first_name is descriptive, but it's a pain to type! user_first_name is just right.
Takeaway: A stranger should be able to read your variable names and guess exactly what your program is doing.
3. Writing Comments
Comments are notes written for humans. When the computer runs your program, it completely ignores anything marked as a comment. In Python, we use the # symbol for single-line comments and triple quotes (""") for docstrings (multi-line documentation).
What to include in your H2 Computing work:
According to the syllabus (1.3.3), your programs should generally include:
1. Program Header: At the very top of your file, include:
- Your Name (Name of programmer)
- The Date written
- A brief Program description (What does this code actually do?)
2. Inline Explanations: Short notes next to or above tricky lines of code to explain why you are doing something.
Example of a good header:
# Programmer: Alex Tan
# Date: 15 October 2023
# Description: This program calculates the average score of a class of students.
Did you know? Even the best programmers forget how their own code works after a few weeks. Writing comments is actually a gift to your "future self"!
Memory Aid (The 3 W's of Comments):
- Who wrote it?
- When was it written?
- What does it do?
Summary and Key Takeaways
Coding standards might feel like "extra work," but they save you from hours of frustration when debugging. Remember these three pillars:
- Structure: Use 4-space indentation and white space to make the logic clear.
- Clarity: Use meaningful identifier names so your code explains itself.
- Communication: Use comments to provide context (Header: name, date, description; Inline: logic explanations).
Keep practicing these standards in every small script you write, and they will become a natural part of your coding "handwriting"!