[MixedUpCody]

Hey everyone,

I am taking an online Java course this semester and this is my first time writing code that others will read, so I was wondering if the amount of comments I have in my code is good. I want to have everything well commented but not be too obnoxious. The program is just to take two test grades from three students and present the average in the output window. Also, I know some of the code could be done more efficiently, but we can only use techniques used in class thus far. Thank you in advance for any suggestions. Have a good day.

import java.util.Scanner; //uses class Scanner

public class Project1
{
    public static void main(String[] args)
    {
        Scanner input = new Scanner(System.in);
        
        // first student's variables
        String firstStudentGiven;
        String firstStudentSur;
        double firstStudentGrade1;
        double firstStudentGrade2;
        double firstStudentAverage;
        
        // second student's variables
        String secondStudentGiven;
        String secondStudentSur;
        double secondStudentGrade1;
        double secondStudentGrade2;
        double secondStudentAverage;
        
        // third student variables
        String thirdStudentGiven;
        String thirdStudentSur;
        double thirdStudentGrade1;
        double thirdStudentGrade2;
        double thirdStudentAverage;
        
        // class variable
        double classAverage;
        
        // first student name prompts
        System.out.println("Please enter the first student's first name: ");
        firstStudentGiven = input.nextLine();
        
        System.out.println("Please enter the first student's last name: ");
        firstStudentSur = input.nextLine();
        
        // second student name prompts
        System.out.println("Please enter the second student's first name: ");
        secondStudentGiven = input.nextLine();
        
        System.out.println("Please enter the second student's last name: ");
        secondStudentSur = input.nextLine();
        
        // third student name prompts
        System.out.println("Please enter the third student's first name: ");
        thirdStudentGiven = input.nextLine();
        
        System.out.println("Please enter the third student's last name: ");
        thirdStudentSur = input.nextLine();
        
        // first student grade prompts
        System.out.printf("Please enter %s %s's first exam score:\n", 
                firstStudentGiven, firstStudentSur);
        firstStudentGrade1 = input.nextFloat();
        
        System.out.printf("Please enter %s %s's second exam score:\n", 
                firstStudentGiven, firstStudentSur);
        firstStudentGrade2 = input.nextFloat();
        // first student average set
        firstStudentAverage = (firstStudentGrade1 + firstStudentGrade2) / 2;
        
        // second student grade prompts
        System.out.printf("Please enter %s %s's first exam score:\n", 
                secondStudentGiven, secondStudentSur);
        secondStudentGrade1 = input.nextFloat();
        
        System.out.printf("Please enter %s %s's second exam score:\n", 
                secondStudentGiven, secondStudentSur);
        secondStudentGrade2 = input.nextFloat();
        // second student average set
        secondStudentAverage = (secondStudentGrade1 + secondStudentGrade2) / 2;
        
        // third student grade prompts
        System.out.printf("Please enter %s %s's first exam score:\n", 
                thirdStudentGiven, thirdStudentSur);
        thirdStudentGrade1 = input.nextFloat();
        
        System.out.printf("Please enter %s %s's second exam score:\n", 
                thirdStudentGiven, thirdStudentSur);
        thirdStudentGrade2 = input.nextFloat();
        // third student average set
        thirdStudentAverage = (thirdStudentGrade1 + thirdStudentGrade2) / 2;
        
        // set class average variable
        classAverage = (firstStudentAverage + secondStudentAverage + 
                thirdStudentAverage) / 3;
        
        // report data
        System.out.println("Student names     Score 1     Score 2     Average");
        
        System.out.printf("%s %s     %.2f     %.2f     %.2f\n",
                firstStudentGiven, firstStudentSur, firstStudentGrade1,
                firstStudentGrade2, firstStudentAverage);
       
        System.out.printf("%s %s     %.2f     %.2f     %.2f\n",
                secondStudentGiven, secondStudentSur, secondStudentGrade1,
                secondStudentGrade2, secondStudentAverage);
       
        System.out.printf("%s %s     %.2f     %.2f     %.2f\n", 
                thirdStudentGiven, thirdStudentSur, thirdStudentGrade1, 
                thirdStudentGrade2, thirdStudentAverage);
        
        System.out.println("The class average is: " + classAverage);
        
        // class average statements
        if(classAverage > 80)
        {
            System.out.println("What an awesome class!");
        }else if(classAverage > 70 && classAverage <= 80)
        {
            System.out.println("Not bad for a first exam.");
        }else
        {
            System.out.println("Looke like we need a new teacher!");
        }
        
    }
}

[GregBrannon]

Some comments:

Your class names may be dictated by the assignments, but if not, you should give your classes meaningful names, names that describe what they do. This one might be StudentGradeAverage.

I think your comments "first this", "second that", "third the other thing" are annoying. I would lean towards "student variables", "name prompts", etc. if you have to, but personally, I don't think even that level of commenting is required. It's pretty obvious what's going on.

However, the level of commenting required is a subjective thing. If you've gotten any hints or guidance from the instructor, the course material, past assignments, or this assignment, try to follow them as best you can. I'd hate to say you've done too much and then have you get dinged for not doing enough. Follow your gut on this one until you get some feedback.

Most books and style guides I've read recommend having a commented header for each source file that includes the source file name, a description, the name of the author, and the date of the source code. That looks something like:

/* File name: source.java
 * 
 * Description: A brief description of what the code
 * does, why it was written, etc.
 *
 * Author: Your name
 *
 * Date:
 */

Doing something like that is entirely up to you, but I think it's a good habit to get into.

[MixedUpCody]

Greg,

Thank you very much for your reply. I appreciate your time.

Cody