Let's not look at conventions related to writing comments generally common should provide all of us 2
of course like describing walk past us or what a mentor does or in some cases describing some block 3
of code with an emitter. 4
Sometimes that may also be some non-obvious design decisions that may go into writing some code and 5
it would be useful to comment those design decisions in the code itself that can be extremely useful 6
for anybody viewing the code. 7
In fact it can be very useful for the owner of the code itself. 8
When he or she reviews the code after a long gap. 9
So if used appropriately comments play an important role. 10
But if you're frequently writing comments then it could reflect poorly on the quality of code. 11
So if you feel compelled to write comments often then you may consider rewriting the code to make it 12
more clearer. 13
Most of the time using good descriptive method and variable names would serve as documentation by itself 14
. 15
That is for the most part we don't have to write any comments at all. 16
For instance here is a search method which searches for a given item in a given area. 17
The method first invokes sort method to sort the ID and then it invokes the binary search method to 18
search in Saturday. 19
As you can see the method names saut and binary search are self-descriptive and we do not need to provide 20
any additional comments. 21
We look at naming conventions to which you should definitely follow encored that is self-descriptive 22
. 23
Without any comments would be very clean and beautiful. 24
As you can see here in the search method. 25
So you should definitely learn to write such good. 26
But if you're ripping an API then you should definitely provide a brief overview of everything that 27
would be part of the API like the public methods. 28
Any public feels and of course the class itself. 29
Java has two types of comments. 30
One is implementation comments under-dressed documentation Commins implementation comments are comments 31
about implementation details re documentation comments are comments for generating API documentation 32
like the July documentation syntax wise implementation comments and while using either double slash 33
or block courts will cause them are learning about absolute basics but just to recap double slashing 34
Bligh's ignore the rest of the line while blockquote imply. 35
Ignore everything in between the two symbols apart from core documentation both double slash and block 36
quotes can also be used to disable one or more lines of code but blockers can also be used to partially 37
disable inline of course. 38
That is to disable it only some part of a single line of code. 39
For example here you can see that only the second condition Y greater than 3 is disabled syntax wise 40
documentation comments. 41
Use something similar to block course but the first symbol involves two asterisks. 42
Documentation comments are generally referred to as dollar documents and you would use them to write 43
Commons for public Appius and they usually do not contain implementation details descriptions that we 44
see in the standard July API and nothing but Javadoc comments. 45
If the source code includes dollar documents then it will call Java or not can be used to extract those 46
comments into history and flights. 47
That is you would see something similar to the July API. 48
You should just go into the bin folder of your local JDK. 49
You'll be able to find a job like Ogburn at the end of this lesson. 50
We will look at a brief them all of inserting Jawa comments using Eclipse and also how we can use Gelada 51
tool from within eclipse to extract those comments into HDMI files. 52
Let's not focus on implementation comments later we will look at documentation comments implementation 53
comments are typically used inside Metternich are they are used with private fields of the class and 54
that's because they signify implementation details and there are three types of implementation comments 55
block comments single line comments and trailing comments. 56
Let's look at each of them as an insiders block comments are used to describe a block of code since 57
a block of code typically involves some non-trivial logic. 58
Describing them would usually involve multiple lines and it is recommended to use block quarterdeck 59
. 60
It is recommended not to use double slash What block comments. 61
Also blockquote should be preceded by a blank blank. 62
Next the names I just single and comments are comments that take up a single line. 63
And so they are short commons. 64
They should be indented with a level of good that follows like blog comments. 65
They should be preceded by a blank line too. 66
You can use either double slash or block chords for single and Corbin's you can see an example here 67
where a rocket is used next just training comments. 68
They are used to provide very short comments that appear on the same line as the. 69
They also come after the chord and it is recommended to place them slightly farther away from the chord 70
in order to separate them from the score. 71
You can once again use either double slash or block chords example shown here indicates that if all 72
involves multiple trailing garments then you should align them to the same column. 73
So for rock comments on blockquote should be used but for single line art creating comments you can 74
use either double slash or block what's known as good documentation comments. 75
My recommendation is to always use documentation comments for describing classes methods and constructors 76
that is use them via that are not the code is part of the public API. 77
Generally they should provide an overview and shouldn't talk about implementation details if any implementation 78
details are to be included in addition to the general overview. 79
Then you can add them separately as block comments. 80
There is no way you can be provided as Gelada comments while implementation details can be uploaded 81
as block comments but I would assume that would be the very rare scenario. 82
Let me know open up my Eclipse and show you how John comments can be inserted and also how we can extract 83
them and find out all of them using that Gelada dogbone. 84
OK this is the basics democracy and in this demo we are going to insert a few Gelada comments and then 85
we will also run the Djala doc tool which would process those comments under Jenrette Hitch's the amount 86
of files describing the API that generated files will be created here in this folder called us doc which 87
is empty right now and this is a standard structure within folder structure within eclipse and all the 88
Hachem ratifiers the API files would be created here. 89
So let's just go ahead and insert some docs. 90
So let's put it back for Alex to put a comment for the class itself. 91
So you would have the heart or slight Hollaback last Asterix and just hit enter and it would create 92
a template. 93
And this is a tag quote at alter. 94
It basically describes the author I'm in the name of the author specified here and you can how more 95
than one author in this case since I'm locked into my machine my account my name has been auto inserted 96
here so let me just put a brief overview of this class and let's go down so that Gelada comments can 97
be inserted for methods classes constructors and or letting as you cannot insert them within a method 98
. 99
You can insert them but if you insert them Witan method there will not be processed by the jailer Doctorow's 100
do they simply ignored by the too. 101
And let's also make sure this is public because we want to create the files for only the API file for 102
only the public stuff. 103
So let's just keep it as public and let's go down. 104
OK here is a matter which has brought our block comments and also Gelada comment. 105
This is a pretty rare scenario. 106
Good block comment. 107
I mentioned that the ovule were going to this Jowler doc comment. 108
But then if you have any implementation details that you want to write you can put that and the block 109
comments but that would be a very rare scenario. 110
And this block comment would be ignored by the Gelada too so it would only process that Djala doc comments 111
. 112
That's what the job I got us. 113
OK so this will be ignored and so on. 114
It's just far but double up or sick and whatever goes into the Jowler document is harder and klank. 115
Whoever is using the API. 116
Now let's scroll down further and here is a matter for parameters and this is also auto generated. 117
So you just do this. 118
So it's going to create this template with the four parameters on you and their names and you can describe 119
what those parameters do. 120
And if there was a return type then there would have been attacked called recruitment. 121
I can describe whatever is being written. 122
So let me just paste this back. 123
That said and he had also there is this Jacquard dot Langrigg integer class which I wanted to show you 124
and as you can see the class itself has disgorgement a hundred or four authors. 125
Similarly if you scroll down so that the main underscore value on the max underscore will you use. 126
They have their own Gelada comments so you can see a lot of comments if you going to this file. 127
I really meant that it has a good nice description a lot of what it does with so rollbacks and here 128
is the return back for this particular method. 129
So now let's just go back here and generate the Jaguar doc had and find you can do it for either the 130
file itself just the file ahrd for the entire project itself which includes all the classes and that's 131
what you will usually do. 132
Let me just do it for you and I might just do it for the entire project. 133
So here you go for the entire project. 134
You can go here project. 135
Even for those files so you will just select the file and you would go into a project. 136
But in this case well let's just do it for the entire project and we would still go into a project. 137
I likely generate Jawa doc and at the top you need to select the Gelug up to. 138
In my case I'm going to use the JDK 1.8 installation and batin the bin folder. 139
How the Jaguar Dokdo so I can you I can pick the Java doc from any of my installations so let me hit 140
on. 141
You can ignore this for now. 142
I just had to finish and now everything has been created here. 143
New files here. 144
There is this next artist here. 145
Right click and say open that web browser and that's it. 146
I here you have all the classes all the packages here are listed here. 147
So let me just go into this class called basics and the basics class. 148
And this is the class in which you mean certain documents. 149
So this is the overview of the class between Surtur and the author name. 150
And these are the different metrics that we have. 151
And this is the type casting method for which we had bought the block comment as well as the doc comment 152
. 153
So this is what I use. 154
This is coming from the Gelada comment. 155
The block comment has been ignored. 156
As I mentioned earlier and this is the method which had the four parameters and you can see in the motard 157
names on its short description of each of the sorted the parameter names on the short description of 158
each of the parameters. 159
And these are some methods. 160
These are public matters but which did not have any Gelada comments. 161
So even they show up. 162
It's just that there is no common source associated with them and that's about it. 163
With regards to the job I talk to under-dog comments and that's it. 164
Finally I just want to see that do we have not yet started coding in Eclipse. 165
The guanaco DeMoss including this one. 166
She shows you the power of Eclipse. 167
So I think it is nice to get a few Fertik lives. 168
We can also use Ajalon or pull out set off eclipse but I think it is totally unnecessary as people saw 169
news eclipse and that's what you would use going forward. 170
It could be eclipse or some other similar ID also. 171
But Id blog you should use all the time and that's it.