Include Comments in Code examples

[CitrusWire]

Godot Documentation Code examples should have comments

Currently the Godot Documentation, and most of the Godot Engine Demos do not have code comments. Code as a rule should of course be commented, but documentation code doubly so.

Reasons this should be done:

• Code is write-once, read-many.
• Documentation code is write-once read-thousands.
• It gets Godot users used to comments in code and hopefully they'll follow the practice, which will benefit them.
• Documentation has the purpose of teaching people about something. It's really hard to learn about something if that something is not explained.
• Code comments lower the barrier to entry. Not everyone is an UberHack3r who can immediately parse and comprehend any code.
• A documented function (i.e. with a docstring) explains succinctly to the user what the function is doing, what the input expected is, and what the output expected is. All things that are extremely useful to know at a glance for any function, but doubly so for documentation functions.
• Allows users to easily skip over functions that don't do what they already know.

This suggestion incorporates the following points (feel free to split into separate issues): 1) Require all future documentation code to include appropriate comments 2) Retroactively add appropriate code comments to all documentation code

3) Require all future Godot Engine Demos to have appropriate code comments 4) Retroactively add appropriate code comments to Godot Engine Demos

---

Documentation; A prime example: https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_styleguide.html Which has "Here is a complete class example based on these guidelines:" - and then a huge wall of code that has only 3 comments at the top. No function comments, no per-line comments, etc. It's not all terrible, scroll down to "Quotes" and that has good code comments, as does "File names", but that's it for the entire document.

Furthermore, there's nothing on that style guide about commenting at all, beyond the fact you can write them. This despite the style guide purports to be influenced by PEP 8, which itself explicitly includes code comments, including via Documentation Strings and PEP 257.

https://docs.godotengine.org/en/latest/getting_started/scripting/c_sharp/c_sharp_style_guide.html isn't any better.

---

Demo's The Demo's also require code comments for the same reasons. I've been playing with the translation one today for example. The code is 17 lines, no comments. Simple enough. Yet despite spending 15 minutes fiddling with it, I still have no idea how Godot knows to go from TranslationServer.setlocale(x) to "change the image/audio to the right file". I know I can find out from a dozen different places online, but that then obviates the point of this demo.

Or the code comments (which do exist) in "Background Thread Loading Demo" - they're written for someone who already knows the Godot systems. # Call deferred to configure max load steps. as the first comment isn't something that's going to be helpful to a new user. Or # Update progress bar, use call deferred, which routes to main thread. - which appears to be assuming I understand Godots threading system, but if someone did that, why would they need to be looking at a Godot demo of it?

But as with the docs, they're not all terrible. "Loading Autoload Demo" has a well code-commented global.gd. (The other two scripts in the project could benefit from having a line in though).

[Calinou]

and most of the Godot Engine Demos do not have code comments.

Please pinpoint specific examples by creating issues in the godot-demo-projects repository. Or, better, open pull requests there :slightly_smiling_face:

[CitrusWire]

Please pinpoint specific examples by creating issues in the godot-demo-projects repository. Or, better, open pull requests there slightly_smiling_face

I've now taken a quick look in 6 of them and only two had decent comments. When 2/3rds of them are woefully bad, and 1/6th of the rest could use improvement, I'd suggest the best solution is to go through all of them and make sure they're all up to snuff. It'll keep Nathan out of trouble. :-) However, I've opened https://github.com/godotengine/godot-demo-projects/issues/529 and https://github.com/godotengine/godot-demo-projects/issues/530

Alas PR's require I have a clue what I'm looking at. And if I did that, I wouldn't be looking at the demos in the first place. ;-)

[YuriSizov]

Please note, that as it currently stands, comments in code blocks are untranslatable. Which is very important for our international users, so I think we should explain the code in the wrapping text as much as possible.

[CitrusWire]

That's an excellent point. In light of that I've created a feature enhancement for translating code-snippets: https://github.com/godotengine/godot-docs/issues/4211

so I think we should explain the code in the wrapping text as much as possible.

I must respectfully disagree. There's some explanation you can do outside of code-blocks, but to be clearest, the code itself needs comments.

For example, this code block (https://docs.godotengine.org/en/stable/tutorials/2d/custom_drawing_in_2d.html)

func draw_circle_arc(center, radius, angle_from, angle_to, color):
    var nb_points = 32
    var points_arc = PoolVector2Array()

    for i in range(nb_points + 1):
        var angle_point = deg2rad(angle_from + i * (angle_to-angle_from) / nb_points - 90)
        points_arc.push_back(center + Vector2(cos(angle_point), sin(angle_point)) * radius)

    for index_point in range(nb_points):
        draw_line(points_arc[index_point], points_arc[index_point + 1], color)

That would be much clearer with inline comments, even though it has surrounding exposition. (Additional suggestion: that specific snippet would also benefit from not having 7 operations happening on a single line var angle_point = deg2rad(angle_from + i * (angle_to-angle_from) / nb_points - 90) - that's far too dense for a docs snippet.)

[NathanLovato]

Before even comments, the code in docs should strive to be as self-documenting as possible. Although for docs, comments can of course be a big plus. But they need to be translatable, and supporting that seems complicated to both implement and maintain at first glance.

An alternative is to break down code blocks into smaller blocks and insert paragraphs of text in between. I think the Your First Game tutorial does this well. We've experimented with that approach and inline comments at GDQuest, and both approaches work. In case you use paragraphs of text, we found putting the complete script for reference at the bottom of the page was beneficial for our students.

[CitrusWire]

Before even comments, the code in docs should strive to be as self-documenting as possible.

But you should never rely on the code being self-documenting.

There's an excellent blog post here on why self-documenting code is a myth: https://dev.to/woubuc/self-documenting-is-a-myth-and-how-to-make-your-code-self-documenting-3h2n Lets be honest here, "self-documenting code" is a thing we developers tell ourselves because we're lazy (and yes, I include myself in that lazy group :-) ). And that's even assuming self-documenting practices are being followed in the first place. Also of course, what's self-documenting to me may be a complete mess to you, and vice-versa.

And on top of that you also have to build the fact that the code in question here is documentation code; its entire purpose is to explain things to users.

But they need to be translatable, and supporting that seems complicated to both implement and maintain at first glance.

A laudable goal, but given the espoused complexity this seems to be a case of "Perfect is the enemy of the good". It's kind of like saying "we shouldn't write any more English documentation until what currently exists has been translated into all target languages".

An alternative is to break down code blocks into smaller blocks and insert paragraphs of text in between.

I think the best option is both. The prose are nice, but the code itself still needs comments for the reasons highlighted in my original post. Prose doesn't ameliorate those issues entirely.

[NathanLovato]

Lets be honest here, "self-documenting code" is a thing we developers tell ourselves because we're lazy

No, not at all. Let's say writing code that's as readable as possible if you prefer that to self-documenting or self-explanatory.

I didn't say anything against comments in code either, just that we should ensure the code we have in the docs should use clear variable and function names. And we should split long operations, as you pointed out above. There's quite a bit of room for improvement in the docs' code examples in that regard, besides adding comments.

this seems to be a case of "Perfect is the enemy of the good". It's kind of like saying "we shouldn't write any more English documentation until what currently exists has been translated into all target languages".

That's quite the exaggeration.

If you put important learning material in the code comments instead of in text paragraphs, that are translated, think about the learning experience of the many users who don't speak English. That's not a fair trade-off.

Splitting the code into snippets of one to several lines works. I write tuts for a living, we've done that plenty of times. It's actually a bit more work for the writer, it ends up a little more verbose than writing inline comments, but that works well for the students, which is what matters.

All in all, the point is that's how the docs are now, not that I don't want inline comments; they're most convenient for the writer, to me. Someone's welcome to look into adding translation support to code comments. But we should favor having explanations in translatable text paragraphs over comments until the latter can be translated.

In other words, this issue depends on #4211

Note I'm only talking about this repository, where the issue is, and not about the godot-demos repository. The demos aren't translatable so sure, they could have clean code and docstrings or comments already.

[CitrusWire]

this seems to be a case of "Perfect is the enemy of the good". It's kind of like saying "we shouldn't write any more English documentation until what currently exists has been translated into all target languages".

That's quite the exaggeration.

At first glance it may seem to be, but it's not really. Consider, how much difference is there between: "We're not going to write comments in code because they can't be translated" and "We're not going to write new docs until the current ones are translated" Both are waiting on translation related stuff before any further work is done on the main thing. The details (and yes, scope) are different but the principle is the same: docs are halted waiting for translation stuff.

So the question is - does the project wait to comment code until 4211 is done? I'd say no. More people will benefit from just English comments than will benefit from no extra comments at all.

---

Comments vs Prose

In general I feel like we're talking around the same thing. I'm not saying "don't do prose to explain code", what I'm saying is that there should definitely be in-line comments that can stand alone from the prose. Simply put: Keep the prose, but add the in-line comments too.

I'm new to Godot so I'm working my way through the docs right now, and I can assure you that at least for this student, I'm struggling with quite a few of the examples because they don't have comments. Yes they have prose, but the comments would help more for me personally. An important component of pedagogy of course is that different people learn differently. In-line comments would help a portion of us.

[CitrusWire]

I'd like to suggest when comments are added that they not be inline comments, but instead "block comments" on the line above.

This is in-line (hah!) with PEP8: https://www.python.org/dev/peps/pep-0008/#inline-comments

Use inline comments sparingly.
...
Inline comments are unnecessary and in fact distracting if they state the obvious. 

(Remembering that for docs code-comments, you do want to be stating the "obvious", because the readers won't know obvious things yet)

[YuriSizov]

In general I feel like we're talking around the same thing. I'm not saying "don't do prose to explain code", what I'm saying is that there should definitely be in-line comments that can stand alone from the prose. Simply put: Keep the prose, but add the in-line comments too.

Can you perchance give an example of a block of code in the docs that can be split into a section of smaller snippets while maintaining the need for the inline comments? Like what you say can hypothetically be possible as long as those comments are not required for understanding the article (since they are not translatable currently), but without a case that can be studied, a good example, we are just talking in concepts. And it's hard for me to imagine what would such comments describe that is not explained in the surrounding text.

Also, a side note from my personal experience trying to code with someone who is completely foreign to the idea: mixing code and comments may be hard to understand for some people, reading comments meaningfully requires some level of understanding of what is comments' purpose. As Godot docs aim to be beginner friendly, this may be a valuable anecdote.

[NathanLovato]

Isn't the general problem that some code examples are poorly written or explained? And yes we should start comparing real examples.

We do both tuts with and without inline comments at GDQuest, and I can confirm that code comments are most accessible to users who have good programming foundations.

[CitrusWire]

And it's hard for me to imagine what would such comments describe that is not explained in the surrounding text.

Sorry, I've not been clear. Leave the prose as it, but add code comments too.

Some people learn through reading prose around comments. But some people learn better through code-comments. Using both helps.

And yes we should start comparing real examples.

The problem I find with real examples is that it's easy to get bogged down in the details of the example rather than the high level concept. Especially if there's a mistake in the example or it's not the best possible example.

That said, here's one

From: https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_styleguide.html There are no comments in this function in the doc. I'm treating it as Python because that's what I know.

func set_is_active(value):
    """ Trigger game player between active/not.

    Parameters:
        value (bool): What state we want to switch to. True = Active; False = Inactive.
    """

    # Update global
    is_active = value

    # Change states
    # ----
    set_physics_process(value)
    set_process_unhandled_input(value)
    set_block_signals(not value)

[NathanLovato]

Let's look at two examples using the above function, to illustrate the difference between inline comments and breaking code into multiple snippets. Below I'm using the Godot 4.0 syntax for docstrings, which is placed above a method, property, or class definition, and starts with ##

---

We can use a property and a setter function to toggle processing of input and updating every frame.

## If true, the state machine processes input and receives signal callbacks.
func set_is_active(value):
    is_active = value
    # We use is_active to activate or deactivate physics process, input processing, and signal blocking.
    set_physics_process(is_active)
    set_process_unhandled_input(is_active)
    set_block_signals(not is_active)

---

We can use a property and a setter function to toggle processing of input and updating every frame. In the function below, if the value is `true, the state machine processes input and receives signal callbacks.

func set_is_active(value):
    is_active = value

We then use the value of is_active to activate or deactivate physics process, input processing, and signal blocking.

    set_physics_process(is_active)
    set_process_unhandled_input(is_active)
    set_block_signals(not is_active)

[NathanLovato]

While I personally prefer the version with comments, notice how you have the same amount of info in both cases. And with the current state of the docs, option 2 gets translated.

[CitrusWire]

I am going to restrain myself from giving specific feedback on that example. :-)

Instead, I'll simply say that to me the best option is to the use the code from number 1, and the text from number 2.

There is no requirement that any given information be conveyed only once. Indeed, pedagogy is clear that repeating things reinforces them, helping learning.

[NathanLovato]

You can write the hybrid you think would be best.

As far as repetition, yes and no. Reviewing the same information over days and weeks reinforces learning. That's part of what practice gives you.

Saying things differently in the same article in such a way the second formulation adds to the first can help. That's something we try to do in the docs, although the docs' quality still varies - there are hundreds of contributors from all around the world.

Paraphrasing or saying the same thing twice, in my experience, doesn't benefit the learner that much.

[Vennnot]

I would vote for closing this issue in favor of more descriptive ones outlining and pointing at specific areas of improvement. Saying "everything could be better" is not helpful or constructive. If there's an issue on every single code page, then an issue with a checkbox for each one would benefit everyone immensely in tracking and actually going through the work.