Glossary
Commenting
The practice of adding explanatory notes within code to make it more understandable for humans, which are ignored by the Java compiler.
Example:
Effective commenting helps a team understand why a complex algorithm was chosen for a specific problem.
Documentation
Written materials that explain the functionality, usage, and design of software, often generated automatically from Javadoc comments.
Example:
Good documentation is crucial for new developers joining a project to quickly get up to speed on existing code.
Javadoc comments
A specific type of multi-line comment starting with `/**` used before classes, methods, and constructors to generate standardized API documentation.
Example:
Using Javadoc comments allows you to automatically create web pages detailing how to use your custom ArrayList class.
Multi-line comments
Explanatory notes in code that begin with `/*` and end with `*/`, used for longer explanations spanning several lines.
Example:
A multi-line comment might describe the overall purpose and design choices of an entire complex method.
Postconditions
Constraints or guarantees about the state of the program or the return value *after* a method or function has successfully completed its execution.
Example:
A postcondition for a sort(int[] array) method is that the array will be in ascending order after the method returns.
Preconditions
Constraints or assumptions that must be satisfied by the input or state of the program *before* a method or function is executed.
Example:
A precondition for a divide(int numerator, int denominator) method might be that the denominator cannot be zero.
Single-line comments
Explanatory notes in code that begin with `//` and extend to the end of the current line, used for brief explanations.
Example:
// This loop iterates through all elements is a common single-line comment before a for loop.