1

00:00:01,110  -->  00:00:07,630
Let's not look at conventions related to writing comments generally common should provide all of us

2

00:00:07,630  -->  00:00:14,550
of course like describing walk past us or what a mentor does or in some cases describing some block

3

00:00:14,550  -->  00:00:16,840
of code with an emitter.

4

00:00:17,770  -->  00:00:24,050
Sometimes that may also be some non-obvious design decisions that may go into writing some code and

5

00:00:24,060  -->  00:00:30,030
it would be useful to comment those design decisions in the code itself that can be extremely useful

6

00:00:30,030  -->  00:00:32,280
for anybody viewing the code.

7

00:00:32,310  -->  00:00:35,790
In fact it can be very useful for the owner of the code itself.

8

00:00:35,880  -->  00:00:39,850
When he or she reviews the code after a long gap.

9

00:00:40,900  -->  00:00:44,220
So if used appropriately comments play an important role.

10

00:00:44,760  -->  00:00:50,700
But if you're frequently writing comments then it could reflect poorly on the quality of code.

11

00:00:50,810  -->  00:00:55,860
So if you feel compelled to write comments often then you may consider rewriting the code to make it

12

00:00:55,860  -->  00:00:57,510
more clearer.

13

00:00:58,500  -->  00:01:04,050
Most of the time using good descriptive method and variable names would serve as documentation by itself

14

00:01:04,050  -->  00:01:04,610
.

15

00:01:04,980  -->  00:01:08,950
That is for the most part we don't have to write any comments at all.

16

00:01:09,090  -->  00:01:14,560
For instance here is a search method which searches for a given item in a given area.

17

00:01:14,940  -->  00:01:20,980
The method first invokes sort method to sort the ID and then it invokes the binary search method to

18

00:01:21,060  -->  00:01:22,830
search in Saturday.

19

00:01:23,400  -->  00:01:29,340
As you can see the method names saut and binary search are self-descriptive and we do not need to provide

20

00:01:29,340  -->  00:01:31,660
any additional comments.

21

00:01:31,680  -->  00:01:38,100
We look at naming conventions to which you should definitely follow encored that is self-descriptive

22

00:01:38,120  -->  00:01:38,160
.

23

00:01:38,190  -->  00:01:41,850
Without any comments would be very clean and beautiful.

24

00:01:42,090  -->  00:01:44,540
As you can see here in the search method.

25

00:01:44,780  -->  00:01:47,110
So you should definitely learn to write such good.

26

00:01:47,610  -->  00:01:53,190
But if you're ripping an API then you should definitely provide a brief overview of everything that

27

00:01:53,190  -->  00:01:56,170
would be part of the API like the public methods.

28

00:01:56,220  -->  00:02:00,440
Any public feels and of course the class itself.

29

00:02:00,810  -->  00:02:02,790
Java has two types of comments.

30

00:02:02,850  -->  00:02:09,210
One is implementation comments under-dressed documentation Commins implementation comments are comments

31

00:02:09,210  -->  00:02:15,930
about implementation details re documentation comments are comments for generating API documentation

32

00:02:16,350  -->  00:02:24,660
like the July documentation syntax wise implementation comments and while using either double slash

33

00:02:24,750  -->  00:02:32,200
or block courts will cause them are learning about absolute basics but just to recap double slashing

34

00:02:32,200  -->  00:02:36,030
Bligh's ignore the rest of the line while blockquote imply.

35

00:02:36,330  -->  00:02:42,680
Ignore everything in between the two symbols apart from core documentation both double slash and block

36

00:02:42,680  -->  00:02:50,040
quotes can also be used to disable one or more lines of code but blockers can also be used to partially

37

00:02:50,040  -->  00:02:51,540
disable inline of course.

38

00:02:51,870  -->  00:02:55,820
That is to disable it only some part of a single line of code.

39

00:02:56,430  -->  00:03:04,830
For example here you can see that only the second condition Y greater than 3 is disabled syntax wise

40

00:03:05,040  -->  00:03:06,450
documentation comments.

41

00:03:06,450  -->  00:03:12,450
Use something similar to block course but the first symbol involves two asterisks.

42

00:03:12,740  -->  00:03:18,750
Documentation comments are generally referred to as dollar documents and you would use them to write

43

00:03:18,750  -->  00:03:25,200
Commons for public Appius and they usually do not contain implementation details descriptions that we

44

00:03:25,200  -->  00:03:29,670
see in the standard July API and nothing but Javadoc comments.

45

00:03:29,850  -->  00:03:35,610
If the source code includes dollar documents then it will call Java or not can be used to extract those

46

00:03:35,610  -->  00:03:37,940
comments into history and flights.

47

00:03:38,070  -->  00:03:41,540
That is you would see something similar to the July API.

48

00:03:41,590  -->  00:03:44,770
You should just go into the bin folder of your local JDK.

49

00:03:44,850  -->  00:03:49,050
You'll be able to find a job like Ogburn at the end of this lesson.

50

00:03:49,180  -->  00:03:55,920
We will look at a brief them all of inserting Jawa comments using Eclipse and also how we can use Gelada

51

00:03:56,010  -->  00:04:01,740
tool from within eclipse to extract those comments into HDMI files.

52

00:04:02,760  -->  00:04:09,030
Let's not focus on implementation comments later we will look at documentation comments implementation

53

00:04:09,030  -->  00:04:16,050
comments are typically used inside Metternich are they are used with private fields of the class and

54

00:04:16,050  -->  00:04:22,290
that's because they signify implementation details and there are three types of implementation comments

55

00:04:22,470  -->  00:04:26,330
block comments single line comments and trailing comments.

56

00:04:26,340  -->  00:04:34,560
Let's look at each of them as an insiders block comments are used to describe a block of code since

57

00:04:34,560  -->  00:04:38,010
a block of code typically involves some non-trivial logic.

58

00:04:38,370  -->  00:04:44,090
Describing them would usually involve multiple lines and it is recommended to use block quarterdeck

59

00:04:44,090  -->  00:04:44,930
.

60

00:04:45,060  -->  00:04:49,530
It is recommended not to use double slash What block comments.

61

00:04:49,530  -->  00:04:52,540
Also blockquote should be preceded by a blank blank.

62

00:04:54,430  -->  00:04:59,440
Next the names I just single and comments are comments that take up a single line.

63

00:04:59,560  -->  00:05:01,670
And so they are short commons.

64

00:05:01,830  -->  00:05:07,040
They should be indented with a level of good that follows like blog comments.

65

00:05:07,080  -->  00:05:10,150
They should be preceded by a blank line too.

66

00:05:10,380  -->  00:05:16,410
You can use either double slash or block chords for single and Corbin's you can see an example here

67

00:05:16,530  -->  00:05:21,600
where a rocket is used next just training comments.

68

00:05:21,630  -->  00:05:26,590
They are used to provide very short comments that appear on the same line as the.

69

00:05:27,090  -->  00:05:33,250
They also come after the chord and it is recommended to place them slightly farther away from the chord

70

00:05:33,540  -->  00:05:35,790
in order to separate them from the score.

71

00:05:36,510  -->  00:05:42,770
You can once again use either double slash or block chords example shown here indicates that if all

72

00:05:42,780  -->  00:05:47,860
involves multiple trailing garments then you should align them to the same column.

73

00:05:48,030  -->  00:05:54,370
So for rock comments on blockquote should be used but for single line art creating comments you can

74

00:05:54,370  -->  00:06:01,250
use either double slash or block what's known as good documentation comments.

75

00:06:01,290  -->  00:06:07,470
My recommendation is to always use documentation comments for describing classes methods and constructors

76

00:06:08,530  -->  00:06:13,340
that is use them via that are not the code is part of the public API.

77

00:06:13,380  -->  00:06:19,210
Generally they should provide an overview and shouldn't talk about implementation details if any implementation

78

00:06:19,200  -->  00:06:22,480
details are to be included in addition to the general overview.

79

00:06:22,770  -->  00:06:26,460
Then you can add them separately as block comments.

80

00:06:26,580  -->  00:06:32,010
There is no way you can be provided as Gelada comments while implementation details can be uploaded

81

00:06:32,010  -->  00:06:37,110
as block comments but I would assume that would be the very rare scenario.

82

00:06:37,180  -->  00:06:43,950
Let me know open up my Eclipse and show you how John comments can be inserted and also how we can extract

83

00:06:44,120  -->  00:06:48,060
them and find out all of them using that Gelada dogbone.

84

00:06:49,260  -->  00:06:55,990
OK this is the basics democracy and in this demo we are going to insert a few Gelada comments and then

85

00:06:55,990  -->  00:07:01,500
we will also run the Djala doc tool which would process those comments under Jenrette Hitch's the amount

86

00:07:01,500  -->  00:07:07,650
of files describing the API that generated files will be created here in this folder called us doc which

87

00:07:07,650  -->  00:07:15,780
is empty right now and this is a standard structure within folder structure within eclipse and all the

88

00:07:15,780  -->  00:07:19,850
Hachem ratifiers the API files would be created here.

89

00:07:19,890  -->  00:07:22,240
So let's just go ahead and insert some docs.

90

00:07:22,290  -->  00:07:26,750
So let's put it back for Alex to put a comment for the class itself.

91

00:07:27,000  -->  00:07:32,460
So you would have the heart or slight Hollaback last Asterix and just hit enter and it would create

92

00:07:32,470  -->  00:07:33,280
a template.

93

00:07:33,450  -->  00:07:36,610
And this is a tag quote at alter.

94

00:07:36,620  -->  00:07:42,070
It basically describes the author I'm in the name of the author specified here and you can how more

95

00:07:42,060  -->  00:07:47,920
than one author in this case since I'm locked into my machine my account my name has been auto inserted

96

00:07:47,910  -->  00:07:56,460
here so let me just put a brief overview of this class and let's go down so that Gelada comments can

97

00:07:56,470  -->  00:08:04,730
be inserted for methods classes constructors and or letting as you cannot insert them within a method

98

00:08:04,750  -->  00:08:04,820
.

99

00:08:04,830  -->  00:08:09,910
You can insert them but if you insert them Witan method there will not be processed by the jailer Doctorow's

100

00:08:09,940  -->  00:08:13,380
do they simply ignored by the too.

101

00:08:13,530  -->  00:08:19,790
And let's also make sure this is public because we want to create the files for only the API file for

102

00:08:19,790  -->  00:08:21,310
only the public stuff.

103

00:08:21,390  -->  00:08:26,200
So let's just keep it as public and let's go down.

104

00:08:27,730  -->  00:08:34,210
OK here is a matter which has brought our block comments and also Gelada comment.

105

00:08:34,240  -->  00:08:35,940
This is a pretty rare scenario.

106

00:08:36,000  -->  00:08:37,240
Good block comment.

107

00:08:37,290  -->  00:08:41,920
I mentioned that the ovule were going to this Jowler doc comment.

108

00:08:42,220  -->  00:08:47,470
But then if you have any implementation details that you want to write you can put that and the block

109

00:08:47,470  -->  00:08:50,610
comments but that would be a very rare scenario.

110

00:08:50,620  -->  00:08:56,760
And this block comment would be ignored by the Gelada too so it would only process that Djala doc comments

111

00:08:56,760  -->  00:08:56,820
.

112

00:08:56,830  -->  00:08:59,000
That's what the job I got us.

113

00:08:59,040  -->  00:09:01,050
OK so this will be ignored and so on.

114

00:09:01,080  -->  00:09:06,720
It's just far but double up or sick and whatever goes into the Jowler document is harder and klank.

115

00:09:06,780  -->  00:09:08,500
Whoever is using the API.

116

00:09:08,940  -->  00:09:16,500
Now let's scroll down further and here is a matter for parameters and this is also auto generated.

117

00:09:16,710  -->  00:09:18,450
So you just do this.

118

00:09:18,880  -->  00:09:24,970
So it's going to create this template with the four parameters on you and their names and you can describe

119

00:09:24,960  -->  00:09:27,110
what those parameters do.

120

00:09:27,330  -->  00:09:31,810
And if there was a return type then there would have been attacked called recruitment.

121

00:09:31,990  -->  00:09:35,950
I can describe whatever is being written.

122

00:09:36,070  -->  00:09:39,360
So let me just paste this back.

123

00:09:39,830  -->  00:09:47,350
That said and he had also there is this Jacquard dot Langrigg integer class which I wanted to show you

124

00:09:48,000  -->  00:09:54,810
and as you can see the class itself has disgorgement a hundred or four authors.

125

00:09:54,820  -->  00:10:00,190
Similarly if you scroll down so that the main underscore value on the max underscore will you use.

126

00:10:00,210  -->  00:10:07,210
They have their own Gelada comments so you can see a lot of comments if you going to this file.

127

00:10:07,300  -->  00:10:14,050
I really meant that it has a good nice description a lot of what it does with so rollbacks and here

128

00:10:14,050  -->  00:10:17,570
is the return back for this particular method.

129

00:10:17,590  -->  00:10:26,980
So now let's just go back here and generate the Jaguar doc had and find you can do it for either the

130

00:10:26,970  -->  00:10:33,890
file itself just the file ahrd for the entire project itself which includes all the classes and that's

131

00:10:33,900  -->  00:10:35,750
what you will usually do.

132

00:10:35,800  -->  00:10:40,440
Let me just do it for you and I might just do it for the entire project.

133

00:10:40,440  -->  00:10:43,240
So here you go for the entire project.

134

00:10:43,440  -->  00:10:45,450
You can go here project.

135

00:10:45,550  -->  00:10:49,440
Even for those files so you will just select the file and you would go into a project.

136

00:10:49,750  -->  00:10:55,310
But in this case well let's just do it for the entire project and we would still go into a project.

137

00:10:55,420  -->  00:11:01,420
I likely generate Jawa doc and at the top you need to select the Gelug up to.

138

00:11:01,440  -->  00:11:07,140
In my case I'm going to use the JDK 1.8 installation and batin the bin folder.

139

00:11:07,160  -->  00:11:13,900
How the Jaguar Dokdo so I can you I can pick the Java doc from any of my installations so let me hit

140

00:11:14,000  -->  00:11:14,210
on.

141

00:11:14,220  -->  00:11:16,060
You can ignore this for now.

142

00:11:16,300  -->  00:11:22,180
I just had to finish and now everything has been created here.

143

00:11:22,170  -->  00:11:23,990
New files here.

144

00:11:24,060  -->  00:11:25,570
There is this next artist here.

145

00:11:25,600  -->  00:11:30,650
Right click and say open that web browser and that's it.

146

00:11:30,640  -->  00:11:35,980
I here you have all the classes all the packages here are listed here.

147

00:11:37,000  -->  00:11:42,660
So let me just go into this class called basics and the basics class.

148

00:11:42,930  -->  00:11:46,580
And this is the class in which you mean certain documents.

149

00:11:46,600  -->  00:11:50,950
So this is the overview of the class between Surtur and the author name.

150

00:11:51,210  -->  00:11:53,510
And these are the different metrics that we have.

151

00:11:53,870  -->  00:11:59,960
And this is the type casting method for which we had bought the block comment as well as the doc comment

152

00:11:59,990  -->  00:12:00,070
.

153

00:12:00,120  -->  00:12:01,850
So this is what I use.

154

00:12:01,890  -->  00:12:04,350
This is coming from the Gelada comment.

155

00:12:04,380  -->  00:12:05,890
The block comment has been ignored.

156

00:12:05,880  -->  00:12:12,180
As I mentioned earlier and this is the method which had the four parameters and you can see in the motard

157

00:12:12,180  -->  00:12:18,030
names on its short description of each of the sorted the parameter names on the short description of

158

00:12:18,030  -->  00:12:19,350
each of the parameters.

159

00:12:19,460  -->  00:12:20,990
And these are some methods.

160

00:12:21,030  -->  00:12:24,920
These are public matters but which did not have any Gelada comments.

161

00:12:24,930  -->  00:12:26,070
So even they show up.

162

00:12:26,080  -->  00:12:33,150
It's just that there is no common source associated with them and that's about it.

163

00:12:33,150  -->  00:12:39,430
With regards to the job I talk to under-dog comments and that's it.

164

00:12:39,510  -->  00:12:44,750
Finally I just want to see that do we have not yet started coding in Eclipse.

165

00:12:44,760  -->  00:12:47,290
The guanaco DeMoss including this one.

166

00:12:47,460  -->  00:12:50,330
She shows you the power of Eclipse.

167

00:12:50,590  -->  00:12:53,830
So I think it is nice to get a few Fertik lives.

168

00:12:53,860  -->  00:13:00,460
We can also use Ajalon or pull out set off eclipse but I think it is totally unnecessary as people saw

169

00:13:00,470  -->  00:13:04,170
news eclipse and that's what you would use going forward.

170

00:13:04,470  -->  00:13:07,930
It could be eclipse or some other similar ID also.

171

00:13:08,130  -->  00:13:12,150
But Id blog you should use all the time and that's it.