Question

Hi I am new to programing and quite confuse how to do the XML commenting and In-Line commenting and I have no programing background and just started 2weeks ago. It is just simple console application calculator. Can u guys check if my XML commenting and in-line commenting is appropriate and formal??

        /// <summary>
    /// Method does:Perform LengthCalculator 
    /// <paramref name="LengthCalculatorOption"/>Determine what is user's input 
    /// <paramref name="AnotherConversion"/> Do while loop condition 
    /// return value: LengthCalculatorOption
    /// </summary>
    /// Pre:  Main menu option input = 1 (Length Calculator) 
    /// Post: Perform Length Calculator
    static int LengthCalculator() {

        int LengthCalculatorOption;

        string AnotherConversion = null;

        do {
            LengthCalculatorMenu(); // Call LenthCalculatorMenu() to display Length Calculator Menu
            LengthCalculatorOption = ValidLengthCalculatorReadOption(); // Call ValidLengthCalculatorReadOption to read the Valid Length Calculator Option

            if (LengthCalculatorOption == 1) { // Do this code if LengthCalculatorOption input == 1 
                ConvertCentimetresToFeetAndInches(); // Call ConvertCentimetresToFeetAndInches() to Convert Centimetres To Feet And Inches
                Console.Write("\nWould you like to make an another Length conversion?" // Ask user if they want to do Another Length Conversion
                             + "\n\n(Enter [Y] to make an another conversion/Enter [N] return to Main menu):");
                AnotherConversion = Console.ReadLine(); // Read AnotherConversion Input
            } else if (LengthCalculatorOption == 2) { // Do this code if LengthCalculatorOption input == 2
                ConvertFeetAndInchesToCentimetres(); // Call ConvertFeetAndInchesToCentimetres() to Convert feet and inches to centimetres
                Console.Write("\nWould you like to make an another Length conversion?"
                             + "\n\n(Enter [Y] to make an another conversion/Enter [N] return to Main menu):");
                AnotherConversion = Console.ReadLine(); // Read AnotherConversion Input
            } else if (LengthCalculatorOption == 3) { // Do this code if LengthCalculatorOption input == 3
                Main(); // Call Main() to return to Main Menu
            } //End if

        } while (AnotherConversion == "Y" || AnotherConversion == "y");// End While , If AnotherConversion = "Y" OR "y", start the do while loop again

        return LengthCalculatorOption;

    }//End LenthCalculator

    //--------------------------------------------------------------------------------------------------------------------------------------------------------------------------

    /// <summary>
    /// Method: Convert Centimetres To Feet And Inches
    /// <paramref name="Centimetres"/> Get the centimetres that user want to conver 
    /// <paramref name="Feet"/> For convertsion Calculation 
    /// <paramref name="Inches"/> For convertsion Calculation 
    /// <paramref name="TotalInches"/> For convertsion Calculation 
    /// <paramref name="CENTIMETRES_PER_INCH"/> Centimetres per inch = 2.54, 
    /// <paramref name="INCHES_PER_FOOT"/> Inches per foot = 12,
    /// return value:
    /// </summary>
    /// Pre: LengthCalculatorOption == 1
    /// Post: Do ConvertCentimetresToFeetAndInches()
    static void ConvertCentimetresToFeetAndInches() {
        double Centimetres = 0.0, Feet = 0.0, Inches = 0.0, TotalInches = 0.0;
        const double CENTIMETRES_PER_INCH = 2.54, INCHES_PER_FOOT = 12;

        Console.WriteLine("Please Enter the Centimetres(cm) that you wish to convert to feet and inches:");
        Centimetres = double.Parse(Console.ReadLine()); //Read the Centimetres enter by user 
        TotalInches = (Centimetres / CENTIMETRES_PER_INCH); // This will take a floor function of Centimetres/2.54
        Feet = (TotalInches - TotalInches % INCHES_PER_FOOT) / INCHES_PER_FOOT; // This will make it divisible by 12
        Inches = TotalInches % INCHES_PER_FOOT; // This will give you the remainder after you divide by 12
        Console.WriteLine("\nThe equivalent in feet and inches is {0} ft {1} ins", Feet, Inches);

    }// End ConvertCentimetresToFeetAndInches

    //---------------------------------------------------------------------------------------------------------------------------------------------------------------------------

    /// <summary>
    /// Method: To Convert Feet and Inches to Centimetres
    /// <paramref name="Centimetres"/> For Conversion Calculation
    /// <paramref name="Feet"/> Get the Feet that user want to conver 
    /// <paramref name="Inches"/> Get the Inches that user want to conver 
    /// <paramref name="CENTIMETRES_PER_INCH"/> Centimetres per inch = 2.54 For Conversion Calculation
    /// <paramref name="INCHES_PER_FOOT"/> Inches per foot = 12  For Conversion Calculation
    /// </summary>
    /// Pre:  LengthCalculatorOption == 2
    /// Post: Do ConvertFeetAndInchesToCentimetres()

    static void ConvertFeetAndInchesToCentimetres() {
        int Feet, Inches; 
        double Centimetres;
        const double CENTIMETRES_PER_INCH = 2.54, INCHES_PER_FOOT = 12;

        Console.WriteLine("Please Enter the Feet:");
        Feet = int.Parse(Console.ReadLine()); // Get the Feet that user want to conver 
        Console.WriteLine("Please Enter the Inches:");
        Inches = int.Parse(Console.ReadLine()); // Get the Inches that user want to conver 
        Centimetres = ((Feet * INCHES_PER_FOOT) + Inches) * CENTIMETRES_PER_INCH;
        Console.WriteLine("The equivalent in centimetres is {0}cm", Centimetres);

    }//End ConvertFeetAndInchesToCentimetres

    ///--------------------------------------------------------------------------------------------------------------------------------------------------------------------------

    /// <summary>
    /// Method: Display the sub-menu of LengthCalculatorMenu
    /// <paramref name="LengthCalculatorMenu"/> SubMenu for LengthCalculator
    /// return value:
    /// </summary>
    /// Pre:  Main menu option input = 1 (Length Calculator) 
    /// Post: LengthCalculatorMenu Displayed

    static void LengthCalculatorMenu() {
        string LengthCalculatorMenu = ("Enter 1) Convert Centimetres to Feet and Inches:"
                                    + "\nEnter 2) Convert feet and inches to centimetres:"
                                    + "\nEnter 3) Cancel this Option And Return to Main Menu:");
        Console.Write(LengthCalculatorMenu);
    }//End LengthCalculatorMenu

    ///--------------------------------------------------------------------------------------------------------------------------------------------------------------------------

    /// <summary>
    /// Method: Allow user to enter valid input for Length Calculator
    /// <paramref name="LengthCalculatorOption"/> Read the input for user's option 
    /// <paramref name="ValidLengthCalculatorOption"/> Determine the validation of input for user's option
    /// </summary>
    /// Pre: ??
    /// Post: ??

    static int ValidLengthCalculatorReadOption() {

        int LengthCalculatorOption;
        bool ValidLengthCalculatorOption = false;

        do {
            LengthCalculatorOption = int.Parse(Console.ReadLine());

            if ((LengthCalculatorOption >= 1) && (LengthCalculatorOption <= 3)) {
                ValidLengthCalculatorOption = true;
            } else {
                ValidLengthCalculatorOption = false;
            } // end if

            if (!ValidLengthCalculatorOption) {
                Console.WriteLine("\n\t Option must be 1, 2 or 3. Please Re-Enter your Option");
                LengthCalculatorMenu();
            } //end if 

        } while (!ValidLengthCalculatorOption); //End While 

        return LengthCalculatorOption;
    }// End LengthCalculatorReadOption

    ///--------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Was it helpful?

Solution

Save yourself a lot of time and remove all the comments, except these

/// <summary>
/// Method: Allow user to enter valid input for Length Calculator
/// <paramref name="LengthCalculatorOption"/> Read the input for user's option 
/// <paramref name="ValidLengthCalculatorOption"/> Determine the validation of input for user's option
/// </summary>

You do not need the pre and post stuff either. The <summary> should look like this:

/// <summary>
/// Allow user to enter valid input for Length Calculator.
/// </summary>
/// <paramref name="LengthCalculatorOption"/> Read the input for user's option 
/// <paramref name="ValidLengthCalculatorOption"/> Determine the validation of input for user's option

No need for the word Method in the summary. Keep your comments minimal, as that aids readability to anyone who needs to know what the method does.

Don't bother with comments in the code unless they do provide value. Too many comments can make reading the code harder, not easier.

EDIT:

I just looked at an XML comment that I wrote and noticed that I make use of the <param> rather than <paramref> e.g.

/// <summary>
/// Blah, blah.
/// </summary>
/// <param name="targetSiteId">The target site identifier.</param>

You should use <paramref> if you are referencing a parameter in another part of the comment e.g.

/// <summary>
/// Blah, blah.
/// </summary>
/// <param name="targetSiteId">The target site identifier.</param>
/// <remarks>Note that the <paramref name="targetSiteID" /> should be non zero.</remarks>
Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow
scroll top