Comments | Godot GDScript Tutorial | Ep 04

Summary

The 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

00:00

📝 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.

05:02

🔍 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.

Keywords

💡Comments

Comments in programming are annotations that are not executed as part of the code but serve to explain the code to human readers. In the context of the video, comments are crucial for understanding the source code, especially for others who may read or maintain the code later. The script mentions two types of comments in GDScript: single-line comments using the pound sign and multi-line comments using triple double quotation marks.

💡Single-line Comment

A single-line comment is a form of comment that applies only to the line on which it appears. In GDScript, as explained in the video, a single-line comment is created using the pound sign (#). Anything following the pound sign on that line is ignored by the compiler and is considered a comment, which helps in making notes or explanations directly beside the code without affecting its execution.

💡Multi-line Comment

A multi-line comment extends over multiple lines and is used to describe larger sections of code or to temporarily disable blocks of code. In the video, it is mentioned that in GDScript, a multi-line comment is created using three double quotation marks. However, it's important to note that in GDScript, this is functionally a multi-line string, not a comment in the traditional sense.

💡Methodology Description Comments

These types of comments are used to explain the reasoning behind the choice of algorithms or methodologies in the code. The video provides an example where a methodology description comment is used to explain why an insertion sort was chosen over a quicksort, illustrating the importance of these comments in conveying the developer's thought process.

💡Metadata Comments

Metadata comments are typically found at the beginning of a script and contain information about the code such as the company name, file name, creation year, maintainers, and copyright. The video script describes an example of metadata comments from the Godot engine on GitHub, showing how they provide essential context about the project and its legal status.

💡Debugging Comments

Debugging comments are used during the development process to help identify and fix issues in the code. The script mentions using comments to disable print statements temporarily, which is a common practice for debugging. Once the issue is resolved, these print statements are commented out, potentially to be revisited later.

💡Code Description Comments

Code description comments are used to clarify the intent of a line or block of code. The video emphasizes the importance of meaningful variable names over comments for clarity, but acknowledges that comments can be used when necessary to explain the purpose of a particular piece of code, such as indicating that a variable represents the player's health.

💡Meaningful Names

Meaningful names in programming refer to the practice of naming variables and functions in a way that clearly indicates their purpose or content. The video script suggests that using meaningful names can reduce the need for comments, as the names themselves can convey the intent of the code, such as a variable named 'playerHealth'.

💡Refactoring

Refactoring is the process of restructuring existing code without changing its external behavior to improve nonfunctional attributes such as readability, maintainability, or performance. The video script implies that refactoring can make the code more readable, which in turn reduces the reliance on comments to explain the code's purpose.

💡Source Control

Source control, as mentioned in the video, refers to the practice of tracking and managing changes to the source code in a project. The script advises against using comments for version control purposes, instead recommending the use of dedicated tools like GitHub or Bitbucket, which are designed to handle version tracking and collaboration more effectively.

💡Compiler

A compiler is a program that translates source code written in a programming language into machine code that a computer can execute. In the context of the video, the compiler reads the source code and ignores comments, whether single-line or multi-line, allowing programmers to include explanatory notes without affecting the code's execution.

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