Require Comments in all future Code examples

[CitrusWire]

Currently the most of the Godot Engine Demos do not have code comments. Code as a rule should of course be commented, but demo 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.

By requiring code-comments in future demo's, the demo's will be better able to serve their purpose of helping new users.

[wajrou]

The code should be documentation of itself. When code needs more comments then it's signal to refactor it (rename the variables, split the code into functions and more classes, change patterns, etc.). Code examples in documentation is exception because it's tutorial to explain the most basic things. Demo projects are useful even as starter project or for copying some feature into custom project and comments are then write-once delete-thousands. When someone doesn't understand what internal function does then the most useful comment is "ctrl+click on function to read the help". Sometimes comment is really handy but scrolling over heavy commented code could make it less readable. It's just an oppinion because I like the power of simplicity.