Documentation and Commenting

 

Documentation and commenting are used to explain to yourself and others exactly what your code is trying to accomplish and how you are approaching the problem. Often times commenting before you write code can help organize your thoughts and make programming easier. Mostly, documentation is for the benefit of others who will read your code after it has been completed.


Documentation can be done during programming or after programming. You are advised to document your code as you write it because it is often the case that, after writing a large program, you have forgotten what your earlier code does and how it works.


Part of your assignment grades will depend on the readability of your code (comments and indentation). You should include the following documentation in your code:

  1. -Block comment at beginning of file that lists:

    1.  Your name, as you want the instructor to write it

    2.  Your email address

    3.  Any remarks that you wish to make to the instructor

  1. -Class documentation: Each class in your code must be preceded by documentation that describes what the class does and for what it will be used.

  2. -Method documentation: Each method in a class should be preceded by documentation that describes the parameters that will be passed in, what the method will do with that data, and what results will be returned.

  3. -Variable documentation: For every instance variable that is declared in your program, that declaration should include a comment that describes what the variable is for. This should be done even when the name of the variable is obvious.

  4. -Internal comments: For long methods, it is sometimes useful to break the code up into chunks that serve a similar purpose and then comment that purpose. The internal documentation should precede the grouping of statements and should describe what they will accomplish. Break up groups with empty lines to improve readability.


Sestoft Section 4 discusses commenting in Java


(Some information on this page is from the NCSU Java Style Guidelines: CSC 116/216)