Coding Standards

Welcome to the official coding standards guide for the Microsoft Developer Network (MSDN). Adhering to these standards ensures consistency, readability, maintainability, and high quality across all MSDN documentation projects.

1. General Principles

• Readability: Code should be easy for humans to read and understand.
• Consistency: Follow established patterns and conventions throughout the project.
• Maintainability: Write code that is easy to modify and extend.
• Simplicity: Prefer straightforward solutions over complex ones.
• Clarity: Avoid ambiguity and strive for clear intent.

2. Naming Conventions

2.1 Variables and Parameters

• Use camelCase for local variables and parameters.
• Start with a lowercase letter.
• Example: let userName;, function calculateTotal(itemPrice, quantity)

2.2 Functions and Methods

• Use PascalCase for public methods and exported functions.
• Use camelCase for private methods (conventionally prefixed with an underscore).
• Example: function ProcessData(), _internalHelper()

2.3 Classes and Constructors

• Use PascalCase for class names and constructor functions.
• Example: class UserProfile, function DatabaseConnection()

2.4 Constants

• Use SCREAMING_SNAKE_CASE for constants.
• Example: const MAX_RETRIES = 3;

3. Formatting and Indentation

3.1 Indentation

• Use 4 spaces for indentation. Do not use tabs.

3.2 Braces

• Place opening braces on the same line as the statement.
• Place closing braces on their own line, aligned with the opening statement.

if (condition) {
    // code block
} else {
    // another code block
}

3.3 Whitespace

• Use a single space around operators (e.g., =, +, -, *, /).
• Use a single space after commas in lists and arguments.
• Use a single space before opening braces for blocks (if, for, function, etc.).

3.4 Line Length

• Aim for a maximum line length of 100 characters. Break long lines logically.

4. Comments and Documentation

4.1 Single-line Comments

• Use // for single-line comments.
• Place comments on a new line or at the end of a line if it doesn't clutter the code.

4.2 Multi-line Comments

• Use /* ... */ for multi-line comments.
• Use for explanatory blocks of text.

4.3 JSDoc

• Use JSDoc for documenting functions, classes, and significant variables.
• This allows for automatic generation of documentation.

/**
 * Calculates the sum of two numbers.
 * @param {number} a The first number.
 * @param {number} b The second number.
 * @returns {number} The sum of a and b.
 */
function add(a, b) {
    return a + b;
}

5. Error Handling

• Use try-catch blocks for handling potential errors.
• Throw custom error objects when appropriate.
• Provide clear and informative error messages.

6. Version Control (Git)

• Use descriptive commit messages.
• Follow the Conventional Commits specification where possible.
• Keep commits small and focused on a single change.

7. Code Reviews

• Participate actively in code reviews.
• Provide constructive feedback and be open to receiving it.
• Code reviews are crucial for maintaining code quality and knowledge sharing.

By adhering to these coding standards, we can collectively build robust, maintainable, and high-quality documentation and code for MSDN.