Documenting Flashcards
What should be included in the documentation of method declarations, and what is the standard notation used in Computer Science to represent variable parts of a string?
The documentation of method declarations should provide an overview of the functionality available through the methods and concise descriptions of how to use that functionality. This can include information on the parameters that the method expects, any return values, and any potential side effects of using the method.
In Computer Science, the standard notation used to represent variable parts of a string is to enclose them in angled brackets (<…>). For example, the string “<first><family>" can be expanded to "Markus Roggenbach" or "Randall Gaya" depending on the values used for the variables. This notation is often used in documentation to indicate that a particular part of a string can vary and needs to be replaced with an appropriate value.</family></first>
What is the purpose of documenting a method declaration?
The purpose of documenting a method declaration is to provide a clear and concise description of the method’s functionality, how the result is computed out of the parameters, and any side effects that the method may have. This information is important for other developers who may be working with the code, as well as for anyone who needs to use the method in their own programs.
What should be included in the description of a method’s functionality?
The description of a method’s functionality should be written in “natural language” and provide a clear and concise summary of what the method does. This should be accessible to non-technical users and provide a general idea of what the method is designed to accomplish.
What information should be included in the documentation of a method’s formula for computing the result?
The documentation for a method’s formula should provide a clear and concise explanation of how the result is computed out of the parameters. This can include any mathematical formulas or algorithms used by the method to generate the output.
Why is it important to explain the parameters of a method in its documentation?
It is important to explain the parameters of a method in its documentation so that other developers and users understand how the method works and what inputs it expects. This can help to avoid errors or unexpected behavior when the method is used, and can make it easier to write code that interacts with the method.
What is the difference between a referentially transparent method and a method that has side effects?
A referentially transparent method is one that always returns the same output given the same input, and has no side effects on the rest of the program. A method with side effects, on the other hand, may modify the state of the program or have other effects beyond just returning a value. It is important to document any side effects that a method may have so that other developers and users understand how it will impact their code.
What is a side effect in a method?
A side effect in a method refers to any change in the global state of a program caused by the method.
How can a method be considered side effect-free?
A method is side effect-free if it does not cause any changes to the global state of a program.
What is an example of a side effect in a method?
An example of a side effect in a method is when the method modifies a global variable, thus causing a change in the overall state of the program.
What does it mean for a method to be referentially transparent?
A method is referentially transparent if its return value remains the same regardless of the program context and identical input parameters.
What is Javadoc?
Javadoc is a document generator from Sun Microsystem for generating documentation in HTML format from Java source code.
What is the format used by Javadoc for documenting Java classes?
The format used by Javadoc for documenting Java classes is called “doc comments”.
Is the “doc comments” format used by Javadoc a standard for documenting Java classes?
Yes, the “doc comments” format used by Javadoc is the de facto industry standard for documenting Java classes.
What is the purpose of the Javadoc command?
The Javadoc command is used to generate HTML documentation from Java source code. The command includes options for specifying the output directory, version number, author name, and other parameters.
What are some important HTML tags that can be used in Javadoc comments?
Some important HTML tags that can be used in Javadoc comments are @author, @version, {@code}, @param, and @return.
