Comments | Godot GDScript Tutorial | Ep 04
Summary
TLDRThe video script explains the importance and types of comments in programming, specifically in GD Script. It describes two methods for writing comments: single-line using the pound sign and multi-line using triple double quotes. Four common types of comments are discussed: methodology, metadata, debugging, and code description. The script emphasizes using meaningful variable names and refactoring before resorting to comments for clarity. It advises against using comments for version control and suggests using platforms like GitHub or Bitbucket instead.
Takeaways
- 📝 Comments are programmer-readable annotations in the source code that help explain the code but are ignored by the compiler.
- 🔑 There are two primary ways to write comments in GDScript: using the pound sign (#) for single-line comments and using three double quotation marks for multi-line comments.
- 💬 Multi-line comments in GDScript are treated as multi-line strings, not actual comments, by the compiler.
- 🔍 Four common types of comments are methodology description, metadata, debugging, and code description comments.
- 🔑 Methodology description comments explain the reasoning behind the choice of algorithms or methods in the code.
- 📜 Metadata comments often appear at the top of scripts and include information like the project name, file name, creation year, maintainers, and copyright.
- 🐛 Debugging comments are used to temporarily disable code, such as print statements, during the debugging process.
- 🛠 Code description comments clarify the purpose of a line of code, but should be used sparingly and after considering meaningful variable names.
- 🔄 It's better to use clear variable names and refactoring to make code self-explanatory before resorting to comments for intent.
- 🤔 Comments should explain the 'why' behind the code, not just the 'how', and should be used when code readability reaches its limit.
- ❌ Avoid using comments as a form of version control or to track changes made by individuals, as tools like GitHub or Bitbucket are more appropriate for this purpose.
Q & A
What are comments in programming?
-Comments are programmer-readable annotations in the source code of a program. They are used to explain the code, making it easier for others to understand the intent and methodology behind the code.
How many ways are there to write a comment in GDScript?
-There are two ways to write a comment in GDScript: using the pound sign (#) for single-line comments and using three double quotation marks for multi-line comments.
What is considered when using the pound sign symbol in GDScript?
-The pound sign symbol is used for single-line comments in GDScript. Anything written after the pound sign is considered a comment and is not part of the actual code that the compiler will read.
Why is a multi-line comment in GDScript treated as a multi-line string?
-A multi-line comment in GDScript is treated as a multi-line string because the compiler reads it as such. It is not a real comment but a string that can be included in the code.
What are the four common types of comments mentioned in the script?
-The four common types of comments mentioned are methodology description comments, metadata comments, debugging comments, and code description comments.
What is the purpose of methodology description comments?
-Methodology description comments are used to explain the reasoning behind the choice of algorithms or methods in the code, rather than just the intent of the code itself.
Where are metadata comments typically found and what do they include?
-Metadata comments are typically found at the top of a script and may include information such as the company name, file name, year of creation, names of maintainers, copyright, and more.
What is the purpose of debugging comments and how are they usually implemented?
-Debugging comments are used during the process of finding and fixing errors in the code. They often involve commenting out print statements to temporarily disable them, with the intention of using them again later.
What is the difference between code description comments and meaningful variable names?
-Code description comments are used to explain the intent of a line of code, whereas meaningful variable names are chosen to inherently convey the purpose of the variable, reducing the need for additional comments.
Why should comments not be used as a source of version control?
-Comments should not be used as a source of version control because they are not designed to track changes made by individuals over time. Instead, version control systems like GitHub or Bitbucket should be used for this purpose.
What is the general rule of thumb for using comments in code?
-The general rule of thumb is that code tells you 'how' something is done, while comments explain 'why' it is done that way. Comments should be used to provide rationale and intent when code alone is not self-explanatory.
Outlines
📝 Understanding Comments in Programming
This paragraph explains the concept of comments in programming, which are programmer-readable annotations within the source code. It discusses two primary methods of writing comments: single-line comments using the pound sign symbol and multi-line comments using three double quotation marks. The paragraph also highlights that in GD script, multi-line comments are treated as strings rather than actual comments. Furthermore, it introduces four common types of comments: methodology description, metadata, debugging, and code description. Methodology description comments are used to explain the reasoning behind certain coding choices, such as why one sorting algorithm was chosen over another. Metadata comments typically appear at the top of a script and may include information like the company name, file name, creation year, maintainers, and copyright. Debugging comments are used to temporarily remove code, such as print statements, for troubleshooting purposes. Lastly, code description comments are used to clarify the intent of a line of code, but the paragraph suggests that meaningful variable names and code structure should be used to convey intent before resorting to comments.
🔍 Best Practices for Using Comments in Code
The second paragraph delves into best practices for using comments in code. It emphasizes the importance of using meaningful variable names to convey the intent of the code, which can reduce the need for comments. The paragraph provides an example where instead of using a comment to explain that a variable represents the player's health, the variable is named in a way that clearly communicates its purpose. It also suggests that additional information, such as the type of variable expected, can be included in the code to further clarify its use. The paragraph advises that comments should be used to explain 'why' something is done, rather than 'how', as the code itself should be self-explanatory. It cautions against using comments as a form of version control or to track changes made by individuals, recommending the use of proper version control systems like GitHub or Bitbucket for such purposes.
Mindmap
Keywords
💡Comments
💡Single-line Comment
💡Multi-line Comment
💡Methodology Description Comments
💡Metadata Comments
💡Debugging Comments
💡Code Description Comments
💡Meaningful Names
💡Refactoring
💡Source Control
💡Compiler
Highlights
Comments are programmer-readable annotations in source code.
There are two ways to write a comment in GDScript: single line with the pound sign and multi-line with three double quotation marks.
Single line comments start with a pound sign and are ignored by the compiler.
Multi-line comments in GDScript are treated as multi-line strings by the compiler.
Four common types of comments are methodology description, metadata, debugging, and code description comments.
Methodology description comments explain the reasoning behind code choices, such as why a specific sorting algorithm is used.
Metadata comments typically include information like the company name, file name, and copyright at the top of a script.
Debugging comments are used to temporarily disable code, like print statements, for troubleshooting purposes.
Code description comments help others understand the intent of a line of code, but should be used sparingly.
Meaningful variable names can often convey the intent of code better than comments.
Comments should explain 'why' the code is written a certain way, not 'how', as the code itself shows 'how'.
Use naming conventions and refactoring to make code readable before resorting to comments.
Avoid using comments as a form of version control or to track changes made by individuals.
For tracking changes, use version control systems like GitHub or Bitbucket instead of comments.
Comments are most effective when they clarify the rationale behind complex or non-obvious code decisions.
In open-source projects, metadata comments often outline the legal terms for using the project under its license.
Transcripts
so what exactly are comments comments
our programmer readable annotations in
the source code of a program writing a
comment is fairly straightforward ngd
script there are two ways to write a
comment the first way to write a comment
is by using the pound sign symbol this
is called a single line comment also
keep in mind that anything written after
the pound sign symbol will be considered
a comment in not part of the actual code
this means you can write both code and a
comment on one single line basically
anything before the pound sign symbol
will be considered code for the compiler
to read and everything after the pound
sign symbol will be skipped by the
compiler the second way to write a
comment in GD script is by using three
double quotation marks followed by your
comments ending with three double
quotation marks something to keep in
mind is that a multi-line comment in GD
script is a multi-line string this means
that the compiler will read your
multi-line comment as the multi-line
comment is not a real comment but rather
just a string you can write in your code
there are many different types of
comments out there however however these
four types of comments you may find
yourself using most of the time you may
find yourself using the methodology
description comments the metadata
comments debugging comments and code
description comments let's go ahead and
take a look at each of these the
methodology description comments can be
used for the explanation of the
methodology you use in your code you
will find yourself using this type of
comment to explain the code rather than
a clarification of the codes intent for
example a person may add a comment to
explain why insertion sort was used
instead of quicksort let's go ahead and
take a look at an example of this so
here we have used a multi-line comment
with the following sentence as you can
see here we are explaining through
comments the reason behind the choice in
our code rather than the intents of the
code this type of comment is considered
the methodology description
comment next we have our metadata
comments these comments you will find
most of the time at the top of the
script and may include the company name
the file name the year the script was
created the names of people who maintain
it
copyright and much much more
let's go ahead and take a look at an
example of metadata come for this
example I took a portion of the metadata
comments you may find yourself seeing if
you look at the Godot engine at github
this is what it may look like if they
wrote this in GT script you can notice
that we have the name of the Godot
engine followed by the website followed
by a copyright the year was created and
who are maintaining it you will usually
find metadata comments in open-source
projects typically to write out in legal
terms that you are free to use the
open-source project however you see fit
depending on the type of license they
are giving away the third type of
comments you may find yourself using a
lot is the debugging comments when you
are using comments for debugging you are
most likely using a brute force
debugging method an example would be
commenting out print statements print
statements is a common way for
programmers to debug code when you are
finish people tend to comment them out
with the idea of using them again later
let's go ahead and take a look at an
example of a debugging comment as you
can see here we have an if statement
followed by a commented out print
statement where we want to see the value
inside of X printed out to the screen
typically you use print statements to
see if something's working and you come
in 10th out so that way it doesn't run
during compile time this is just a
simple example however you may find
yourself using this quite a lot when
you're trying to debug issues with your
code in the game the last type of
comment is the code description comment
generally used to make others understand
the intent of the line of code this is
vastly different than explaining the
methodology or the reason you chose
the code this type of comment should be
used only when needed let's go ahead and
take a look at a few examples this is an
example I typically find beginners using
a lot what they'd like to do is they
tend to name their variables x and y
because that's what they tend to read in
articles however they use comments to
explain the intent of the code in this
case the programmer has decided to let
you know that the variable X represents
the player's health this is one way to
use comments however there's a better
way to explain this line of code then
using a comment let's go ahead and take
a look at what this would look like as
you can see here instead of using a
comment to explain the intent of our
code we chose to instead name our
variable something meaningful to explain
the intents of the code in this case
this is better as we get rid of one line
of comment and yet the intention or
rather the store we're trying to tell
other programmers is this variable will
represent the player's health
now that we've named our variable
something meaningful we can do even more
to explain to other programmers the
intent of our code let's go ahead and
take a look at what this would look like
as you can see here we have let other
programmers know that we intend to use
this variable for player's health and
that this variable should only be an
integer this is an even better way of
describing to other programmers the
intent of our code without using comment
now I'm not saying that you shouldn't
use comments to describe the intents of
your code but rather you should first
maximize the use of meaningful names and
code intention first before using
comments to describe the intention of
your code when should you use comments
there's a saying code tells you how and
comments tell you why I generally like
to attempt to use naming conventions and
refactoring to make my code readable
keep in mind that explaining yourself
with code has its limits when you have
reached that limit then you may use
comments to explain why and the
rationale behind your code when to not
use comments you
never use comments as a source of
version or source control that is to say
never ever ever use comments to explain
which person did what what that person
changed in the code and when that person
made the change when working in a group
and if information above is important
use github bitbucket or get a Oh
浏览更多相关视频
Karel Python - Commenting Code
3 | Learn About PHP Syntax for Beginners | 2023 | Learn PHP Full Course for Beginners
Introduction to Spyder - Part 2
20 Advanced Coding Tips For Big Unity Projects
Book summary video kaise banaye | How to make book summary video | Whiteboard animation
P_06 print() function & String concatenation(using +) in Python | Python Tutorials for Beginners
5.0 / 5 (0 votes)