Chapter:Classes - Commenting code

From Juneday education
Jump to: navigation, search

Meta information about this chapter

Expand using link to the right to see the full content.

Introduction

Comments are an important part of both source code a programmer reads, and source code that a programmer produces. We will in this short method show the various types of comments on a syntactic level. How to write good comments and what not to comment is a topic for almost a dedicated course (at least a lecture). In this introductory material, the focus will then be at the syntax, even if we use comments a lot in our examples which might or might not be examples of good commenting style.

Purpose

The purpose is to show the students how to make comments in a source code file. One reason to put this in the chapters about classes, is that classes are the things closes to code production in Java (whereas "objects" for instance are more of an abstract concept). When walking through the various elements in a Java source code file for a class, we cannot leave out the fact that often a great deal of the text in the source code are comments meant for humans.

Goal

After this chapter, the student shall understand:

  • how to write a comment syntactically
    • single line comment
    • multi-line comment (javadoc are shown but not taught)
  • that source code is written by and for humans - which is why comments are a natural part of it

Instructions to the teacher

Common problems

Some students may be intrigued by the javadoc system. Explain that javadoc is outside the scope of this material but that there are many good resources available online. Also mention that a good way to learn how to write javadoc comments is to investigate other people's code and compare with the generated documentation. The Java API source code is a great source of inspiration, and our code examples sometimes has online generated documentation (some of the assignments for instance) generated from the source code.

Explain to the students that high-level programming languages like Java was invented in order to make programming easier for humans. They allow us to express ourselves in a formal language closer to how we think and speak compared to machine code or assembly languages. So, the code we write in Java is meant to be understood not only by the compiler, but also other humans and this is why we include comments. The compiler, of course, couldn't care less about human language and that's why it will ignore all comments.

Introduction to Comments and documentation

Imagine going back to classes you wrote some years ago. Or image reading someone else's classes. It is sometimes hard to understand what the class does, or at least intends to do. Java provides an easy way to write comments, which is text not considered as code and therefore ignored by the compiler. There are two ways to write comments in your code.

There is a format way you can use when writing comments with which you can create manuals for classes and packages. See the javadoc section of the Java page.

single line

You start a single line comment like this.

 
// This is a single line comment

Using "//" makes the compiler ignore everything after (and including) the "//". So the comment "This is a single line comment" is ignored.

Let's illustrate this in a class:

 
package org.commenteers;

public class Example { // Compiler ignores this                                   

  // main method, starting point                                              
  public static void main(String[] args) {
    // Print a welcome message                                              
    System.out.println("Welcome to the example class ... ");
  }

}

multi line

You start a multi line comment like this.

 
/*

and end it like this:

 
*/

A multi line comment looks like this:

 
/* 
  This is a multi line comment
   ... bla bla
*/

Using "/*" and "*/" makes the compiler ignore everything between (and including). So the comment "This is a multi line comment ... bla bla" is ignored by the compiler.

Let's illustrate this in a class:

 
package org.commenteers;

/*                                                                              
  This class is just a simple example                                           
  on how to comment code in Java                                                
                                                                                
 */

public class Example { // Compiler ignores this                                   

  // main method, starting point                                              
  public static void main(String[] args) {
    // Print a welcome message                                              
    System.out.println("Welcome to the example class ... ");
  }

}

Here's an example of how JavaDoc comments look. In this case, it documents a constructor:

  /**
   * Constructs a new Student.
   * @param name The name of the new Student
   * @param birthDate The birthDate of the new Student
   */
  public Student(String name, LocalDate birthDate) {
    this.name = name;
    this.birthDate = birthDate;
  }

Chapters about classes

Here are the chapters about classes in this book, so that you can keep a check on your progress:

Links

Videos and slides

Java Classes Comments (Full playlist) | Java - Classes - Comments | Classes - Comments (pdf)

Further reading

Where to go next

Next page has exercises for this chapter: Classes_-_Commenting_code_-_Exercises

« PreviousBook TOCNext »