02 - Java Basics/006 Comments in Java source code_en.srt

1
00:00:05,000 --> 00:00:07,000
In this lecture, we'll run with you.

2
00:00:07,000 --> 00:00:12,000
What comments are and what type of comments are available in Java source code and apart from that,

3
00:00:12,000 --> 00:00:16,000
we'll talk together regarding Deep's and best practices while using comments.

4
00:00:17,000 --> 00:00:20,000
First of all, let's come up with a common definition here.

5
00:00:21,000 --> 00:00:25,000
The Java comments are statements that are not executed by GBM.

6
00:00:25,000 --> 00:00:31,000
The comments can be used to provide information or explanation about the variable method class or any

7
00:00:31,000 --> 00:00:32,000
statement.

8
00:00:32,000 --> 00:00:35,000
It can also be used to hide program code temporarily.

9
00:00:36,000 --> 00:00:40,000
Comments often used to live so-called to do comments mentions.

10
00:00:40,000 --> 00:00:43,000
Do not forget to restructure code or to add something in the future.

11
00:00:44,000 --> 00:00:46,000
There are three types of comments in Java.

12
00:00:46,000 --> 00:00:49,000
Single line, multiline and Javadoc.

13
00:00:50,000 --> 00:00:54,000
Let's take a closer look at how comments are looked like in our clip's workspace.

14
00:00:56,000 --> 00:01:02,000
Here is our hello world application, which we all know, let's add a single line comment right after

15
00:01:02,000 --> 00:01:03,000
console output.

16
00:01:04,000 --> 00:01:10,000
That was to do at more court here in the future.

17
00:01:11,000 --> 00:01:17,000
By the way, in the clips, if you want to find all to do comments in your code, just go to window

18
00:01:17,000 --> 00:01:19,000
shoyu desks.

19
00:01:20,000 --> 00:01:21,000
Here it is.

20
00:01:22,000 --> 00:01:29,000
Just don't forget to save your file before that eclipse passes all to the comments and lists it here.

21
00:01:29,000 --> 00:01:31,000
I used this too many times.

22
00:01:32,000 --> 00:01:34,000
There is a hotkey for single line comment.

23
00:01:35,000 --> 00:01:41,000
For example, you can comment this code line by pressing control plus slash and uncommented in the same

24
00:01:41,000 --> 00:01:42,000
way.

25
00:01:42,000 --> 00:01:49,000
You can select few lines, for example, the whole method, and call it the same way with hotkeys.

26
00:01:50,000 --> 00:01:58,000
And uncommented, if you wish, with the hotkeys now let's create multiline common type slash asterisk

27
00:01:58,000 --> 00:01:59,000
and enter.

28
00:02:00,000 --> 00:02:07,000
You see how Eclipse helps us to write Multiline Command, you can type something like this, please

29
00:02:08,000 --> 00:02:11,000
do not remove this quote.

30
00:02:12,000 --> 00:02:18,000
And now let me show you, Javadoc, the first thing you should know about Javadoc is that this type

31
00:02:18,000 --> 00:02:23,000
of comments can be converted to nice looking TAMAO pages in JDK.

32
00:02:23,000 --> 00:02:29,000
We have Javadoc program which generates these e-mail pages out of our source code.

33
00:02:30,000 --> 00:02:31,000
Let me show you example.

34
00:02:32,000 --> 00:02:35,000
Here is official javadoc of string class.

35
00:02:35,000 --> 00:02:39,000
You can see class description, constructor, fields' methods.

36
00:02:40,000 --> 00:02:41,000
All of them are clickable.

37
00:02:42,000 --> 00:02:43,000
For example, let me click here.

38
00:02:44,000 --> 00:02:46,000
You can generate the same documentation.

39
00:02:46,000 --> 00:02:48,000
Let's learn how to do this.

40
00:02:49,000 --> 00:02:52,000
Let's create Java documentation for our main method.

41
00:02:53,000 --> 00:02:56,000
Slash Nebel Asterisk Enter.

42
00:02:57,000 --> 00:03:02,000
And here your comment goes the entry point to that program.

43
00:03:04,000 --> 00:03:12,000
You can see the stack there, it is used to add parameter to parameter section in Javadoc, I will share

44
00:03:12,000 --> 00:03:15,000
with you more tags to learn in the homework section.

45
00:03:16,000 --> 00:03:18,000
Meanwhile, let's add clarification here.

46
00:03:19,000 --> 00:03:21,000
Input arguments.

47
00:03:22,000 --> 00:03:25,000
Let's also add Javadoc to our class.

48
00:03:27,000 --> 00:03:31,000
You can see Ostertag here, I will leave the next comment here.

49
00:03:32,000 --> 00:03:35,000
Hello, world application.

50
00:03:36,000 --> 00:03:44,000
Now we can save the file, we are good to generate javadoc to generate javadoc from Eclipse Project,

51
00:03:44,000 --> 00:03:52,000
generate javadoc you configurations you can configure output folder for your documentation.

52
00:03:52,000 --> 00:03:56,000
I will leave default settings here and will press finish.

53
00:03:58,000 --> 00:04:06,000
Now, you can see that dog directly appeared in our project, let's expand it, find index, dot Ashton,

54
00:04:06,000 --> 00:04:08,000
nail file and open it.

55
00:04:08,000 --> 00:04:13,000
You can open it in any browser or you can just use built in Eclipse browser.

56
00:04:14,000 --> 00:04:14,000
Right.

57
00:04:14,000 --> 00:04:17,000
Click open with Web browser.

58
00:04:19,000 --> 00:04:23,000
And here we have our documentation, congratulations.

59
00:04:24,000 --> 00:04:27,000
This is your first documentation to your first program.

60
00:04:27,000 --> 00:04:29,000
You see our class here.

61
00:04:29,000 --> 00:04:31,000
Here's our class description.

62
00:04:31,000 --> 00:04:37,000
Orser Constructor's Method's, here is our main message description.

63
00:04:38,000 --> 00:04:40,000
And here's our arguments description.

64
00:04:41,000 --> 00:04:45,000
Let me share with you tips and best practices of using comments in Java.

65
00:04:46,000 --> 00:04:51,000
The first thing you need to remember in case you want to comment, chunk of code to hide this code,

66
00:04:51,000 --> 00:04:54,000
just remove it if you don't need this code.

67
00:04:55,000 --> 00:04:58,000
That means you don't need this code.

68
00:04:58,000 --> 00:05:05,000
I faced with this so many times when developers comments there or others code and leave it just in case.

69
00:05:05,000 --> 00:05:09,000
Be smart, you will learn how to use version control systems.

70
00:05:09,000 --> 00:05:16,000
And believe me, there is no such cases when you need to leave code just in case, especially when you

71
00:05:16,000 --> 00:05:21,000
have a version control system, because this will end up having a lot of comment at code, which nobody

72
00:05:21,000 --> 00:05:25,000
knows what is it for and you won't be able to support it.

73
00:05:25,000 --> 00:05:30,000
My next advice always remember that comments require maintenance.

74
00:05:30,000 --> 00:05:33,000
You need to keep them up to date and relevant.

75
00:05:33,000 --> 00:05:35,000
Don't forget about this.

76
00:05:35,000 --> 00:05:40,000
I'm trying to be a good tutor and I am saying that right in Javadoc is great.

77
00:05:40,000 --> 00:05:43,000
But also I have to prepare you for real life.

78
00:05:44,000 --> 00:05:45,000
In real life.

79
00:05:45,000 --> 00:05:48,000
You would notice that not all developers write comments.

80
00:05:48,000 --> 00:05:49,000
Why?

81
00:05:49,000 --> 00:05:56,000
Because sometimes they are not needed because you have live documentation, your unit tests in your

82
00:05:56,000 --> 00:05:59,000
test data as you change your code.

83
00:05:59,000 --> 00:06:04,000
We'll discuss in later lessons Giggie approach and goals of unit testing.

84
00:06:04,000 --> 00:06:11,000
But for now, just remember, in case you have solid unit test code coverage and you follow Jawa naming

85
00:06:11,000 --> 00:06:17,000
conventions and choose meaningful names for variables and methods, sometimes javadoc in this case is

86
00:06:17,000 --> 00:06:21,000
redundant so they will learn what comments are.

87
00:06:21,000 --> 00:06:24,000
Now we also know what types of comments we have in Java.

88
00:06:25,000 --> 00:06:31,000
You saw how to generate Javadoc from the source code and also I shared with you tips and best practices

89
00:06:31,000 --> 00:06:33,000
of common usage in real life.

90
00:06:34,000 --> 00:06:42,000
And your homework created Javadoc for your Hello World application and generate documentation from your

91
00:06:42,000 --> 00:06:42,000
source code.

92
00:06:43,000 --> 00:06:46,000
Also, during the lesson you saw only a few javadoc decks.

93
00:06:47,000 --> 00:06:53,000
There are no need to go over each of them because most of them self describing, you know, already

94
00:06:53,000 --> 00:06:54,000
how to use them.

95
00:06:54,000 --> 00:06:58,000
Just take a look through this table to know what other text you can use.