Introduction
Comments - it would seem that it could be easier, and why write an entire article here. But it's not all that simple. As my boss used to say, anyone can write code, but it's hard to write a good commentary. Most language courses start with the traditional Hello World. Even in the Oracle Tutorials, in the "Getting Started" section, we start with The "Hello World!" application . And from the very first lines of code, we see them - Java comments. Their importance is also emphasized by the fact that in such an important document as the Java Code Convention, comments are given a separate section: Comments . As the documentation says, comments in Java are divided into two types:- implementation comment (or code comment);
- documentation comment.
Java code comments
From the name it is clear that this comment refers to the code and should reflect its features. Code comments are:-
Lowercase (i.e. described in one line)
// Строчный комментарий System.out.println("Hello, World!");
-
Block (that is, they are described by a whole block, because they do not fit on one line)
/* * Блочный комментарий */ System.out.println("Hello");
Every time you write a comment, wince and feel like a failure."It is clear that there is no absolute truth, and sometimes comments are necessary. But there are always options, and excessive comments must be fought. The same chapter mentions unusual comments, TODO:
// TODO: Добавить World
System.out.println("Hello, ");
The point is that they can be handled in a special way by the IDE. For example, in IDEA they are collected on a separate tab where they can be viewed:
Comments for documentation
Documentation comments describe the public API. An API is an application programming interface, that is, those classes and methods that are available to other developers to perform any actions. In short, these comments should explain why this or that class and package was created and what this or that method does. You can also describe class fields if necessary. It is exactly what is formatted as a JavaDoc that we see in our IDE tooltips. For example:package test;
/**
* This is a JavaDoc class comment
*/
public class JavaDocTest {
/**
* This is a JavaDoc public field comment
*/
public static final String HELLO_MESSAGE = "Hello, World!";
public static void main(String... args) {
JavaDocTest.greetings();
}
/**
* This is a JavaDoc public method comment
*/
public static void greetings() {
System.out.println(HELLO_MESSAGE);
}
}
After that, we can execute the following command from the directory that contains our package directory: javadoc -d ./test test
After that, we will see the documentation generation process.
Conclusion
As we can see, it would seem that such a simple thing as comments actually turns out to be much more complicated. Therefore, if comments are given some time and followed, your code will be better and you as a programmer will be more valuable. #ViacheslavWhat else to read: |
---|