godotengine / godotengine/godot-docs

Include Comments in Code examples

Open
#4,188 17 comments 2 reactions 0 assignees View on GitHub
enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

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

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the GDScript style guide and the C# style guide linked in the issue, then inspect the translation and Background Thread Loading demos mentioned. Determine the scope and standards for appropriate comments across documentation examples and demos; completion would require an agreed scope and documented coverage of the selected examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.