Comments and Documentation

Introduction

Comments can only be used to explain what code can’t. Whether the code is visible or not.

Copyrights

Comments highlighting copyrights should follow this pattern:

Do

    // ---------------------------------------------------------------
    // Copyright (c) Coalition of the Good-Hearted Engineers
    // FREE TO USE TO CONNECT THE WORLD
    // ---------------------------------------------------------------

Don't

    //----------------------------------------------------------------
    // <copyright file="StudentService.cs" company="OpenSource">
    //      Copyright (C) Coalition of the Good-Hearted Engineers
    // </copyright>
    //----------------------------------------------------------------

Also, Don't

   /* 
    * ==============================================================
    * Copyright (c) Coalition of the Good-Hearted Engineers
    * FREE TO USE TO CONNECT THE WORLD
    * ==============================================================
    */

Methods

Methods that have code that is not accessible at dev-time, or perform a complex function should contain the following details in their documentation.

• Purposing
• Incomes
• Outcomes
• Side Effects