search

gdquest-demos / godot-kickstarter-2019

Create your Own Games with Godot, the Free Game Engine: sources from the January Kickstarter project from GDQuest
MIT License
244 stars 270 forks source link

Elaborate on best practices #19

Closed razcore-rad closed 5 years ago

razcore-rad commented 5 years ago

@NathanLovato I made some modifications to the code guidelines first few chapters as well, where I felt like some things could be improved upon. Also where there were "bugs" like in the order: constants, export etc. Please check and let me know if you find anything wrong.

I've added a chapter on more concrete best practices of what I've been thinking of, revealed while experimenting on OpenRPG. It needs a couple of pairs of eyes for some proof reading. Also let me know if you find something that you might disagree with because we haven't discussed all of this before.

Thanks

check the rendered file directly: https://github.com/razcore-art/kickstarter-quest-3/blob/code-guidelines/docs/code-guidelines.md

NathanLovato commented 5 years ago

Can you use a spell and grammar checker? ispell and langtool will do the trick

NathanLovato commented 5 years ago

The figures are the top don't read well at all. I think it's too abstract from the start, and that sentences like

It's very easy to imagine how even a simple scene tree like the one in Fig. 4 can quickly become unmaintainable if all this flexibility isn't managed.

Won't resonate with most contributors. Mantras like "just make it work" are common in game development, even Juan recommends that, so I think it's going to be hard to get the message across. In general, you should ban "easy", "simple" etc. from these docs. Also, avoid the passive voice.

NathanLovato commented 5 years ago

If you're done with this pass, may I merge and edit directly? It'll be faster than leaving comments everywhere.

razcore-rad commented 5 years ago

If you're done with this pass, may I merge and edit directly? It'll be faster than leaving comments everywhere.

Yes that's fine with me.

When I was writing it I knew some passages are too abstract but it was too late for my brain to make an effort to think differently. I should learn one of these days how to properly use a spell checker in vim, that's true, one of the modern unsolved mysteries.

Do you need the raw svg file I used in making the figures?

edit I mean I guess it's just easier if you decide given the option :) nodes.zip