Teaching Guideline: Programming Style — Names,
Documentation & Format, Refinement & Modularity
1. Teaching Outline
A. Introduction to Programming Style
• Definition: The conventions and best practices developers follow to write clean, readable, and
maintainable code.
• Importance: Improves collaboration, debugging, and code longevity.
B. Naming Conventions
• Key Definitions:
‣ Identifier: Name given to variables, functions, constants, etc.
• Important Rules & Conventions:
‣ Use meaningful, descriptive names.
‣ Consistent casing style:
– camelCase (e.g., totalSum)
– snake_case (e.g., total_sum)
– PascalCase for types, structs.
‣ Avoid single-letter variables except in loops (i, j).
‣ Use nouns for variables and functions that return a value.
‣ Use verbs for function names (e.g., calculateSum()).
‣ Constants in uppercase MAX_SIZE.
• Examples:
int studentAge;
float calculateArea(float radius);
#define MAX_STUDENTS 30
• Common Mistakes:
‣ Using unclear names like x, data, or temp.
‣ Inconsistent naming styles in the same program.
• Real-world Application:
‣ Large projects with multi-person teams.
C. Documentation
• Key Definitions:
‣ Inline comments, block comments, and documentation comments.
• Best Practices:
‣ Comment why, not what (avoid obvious comments).
‣ Use clear, concise language.
‣ Document function purpose, parameters, return values.
‣ Document complex logic and assumptions.
• Syntax:
‣ Single line comments: // comment
‣ Multi-line comments: /* comment */
• Examples:
// Calculate the area of a circle given the radius
float calculateArea(float radius) {
return 3.14 * radius * radius;
}
• Common Mistakes:
‣ Over-commenting trivial code.
‣ Outdated comments that no longer reflect code.
• Real-world Application:
‣ Code maintenance and API documentation.
D. Formatting and Code Layout
• Key Rules:
‣ Consistent indentation (usually 2 or 4 spaces).
‣ Proper use of braces {}.
‣ Line length limits (80-100 characters).
‣ Blank lines to separate logical blocks.
‣ Align related code vertically when helpful.
• Examples:
if (condition) {
// indented block
doSomething();
} else {
doOtherThing();
}
• Common Mistakes:
‣ Mixing tabs and spaces.
‣ Missing braces leading to bugs.
‣ Inconsistent indentation.
• Real-world Application:
‣ Readable code in open source and professional projects.
E. Refinement and Clean Code Principles
• Key Concepts:
‣ Refactor to remove duplication.
‣ Keep functions short and focused.
‣ Use meaningful variable scope (local vs global).
‣ Avoid magic numbers — use named constants.
• Examples:
#define PI 3.14159
float areaCircle(float radius) {
return PI * radius * radius;
}
• Common Mistakes:
‣ Long functions doing too many things.
‣ Hardcoding values repeatedly.
• Real-world Application:
‣ Code evolution and bug reduction.
F. Modularity and Separation of Concerns
• Key Definitions:
‣ Breaking program into independent modules/functions.
• Importance:
‣ Easier testing and maintenance.
‣ Code reuse.
• Techniques:
‣ Use functions to encapsulate logic.
‣ Create header files for declarations.
‣ Separate implementation (.c) and interface (.h).
• Examples:
// math_utils.h
float calculateArea(float radius);
// math_utils.c
#include "math_utils.h"
float calculateArea(float radius) {
return 3.14 * radius * radius;
}
• Common Mistakes:
‣ Monolithic main functions.
‣ Global variables overuse.
• Real-world Application:
‣ Large software systems, APIs, libraries.
2. In-Class Practice Questions
Question 1: Naming Practice (Basic)
• Problem: Rename the variable a to a more meaningful name in this code snippet:
int a = 10;
int b = 20;
int c = a + b;
• Concept Tested: Naming conventions for variables.
• Hint: Think about what the variables represent.
Question 2: Writing Comments (Basic)
• Problem: Add a comment explaining the purpose of this function:
int square(int x) {
return x * x;
}
• Concept Tested: Effective and meaningful documentation.
• Hint: Describe what the function does, not how.
Question 3: Correct Indentation and Braces (Intermediate)
• Problem: Fix the formatting of this code snippet:
if(x>0){
printf("Positive");
}else
{
printf("Non-positive");
}
• Concept Tested: Formatting and code readability.
Question 4: Refactoring into Functions (Intermediate)
• Problem: Refactor this repeated code so it’s modular:
printf("Area of circle: %f\n", 3.14 * r1 * r1);
printf("Area of circle: %f\n", 3.14 * r2 * r2);
• Concept Tested: Modularity and avoiding code duplication.
• Hint: Create a function to calculate the area.
Question 5: Modularizing Code with Header and Source Files (Advanced)
• Problem: Given a main program that calculates areas, outline how you would organize it with
header and source files.
• Concept Tested: Separation of concerns, modularity in project structure.
• Hint: Identify the functions, create .h for declarations and .c for implementations.
3. Homework Practice Questions
Homework 1: Naming and Documentation (Basic)
• Problem: Write a simple C program that calculates the area of a rectangle. Use clear variable
names and add comments explaining the code.
• Concept Tested: Naming conventions and documentation.
Homework 2: Formatting Code (Intermediate)
• Problem: Given poorly formatted code, rewrite it with proper indentation, spacing, and braces:
for(int i=0;i<5;i++){
printf("%d\n",i);}
• Concept Tested: Code format and readability.
Homework 3: Refinement (Intermediate)
• Problem: Refactor this code to eliminate magic numbers and improve readability:
int circumference = 2 * 3.14 * radius;
• Concept Tested: Use of named constants (#define or const).
Homework 4: Creating Modular Functions (Advanced)
• Problem: Write a C program split into two files (math_ops.c and math_ops.h) that provide
functions to compute the area of a circle and the circumference. Include proper documentation
and modularize your code.
• Concept Tested: Modularity, header/source files, documentation.
Homework 5: Code Review and Improvement (Advanced)
• Problem: Review the following code snippet. Identify at least three style problems and suggest
improvements:
int x=0;
void foo(){
for(x=0;x<10;x++){
printf("%d",x);}
}
• Concept Tested: Style critique, naming, scope, formatting.
Additional Tips for The Teacher:
• Encourage live coding demonstrations.
• Highlight the difference a good style can make by showing poorly styled vs well-styled code.
• Use pair programming or group discussion for in-class exercises.
• Provide quick quizzes or flash cards for naming conventions and formatting.
• Use real open-source projects to exemplify modularity and documentation standards.