Generic coding thread

[Mperonen]

Greetings. My name is Mikko-Pentti Einari Eronen and I’m probably the least qualified person to write this post.
I have been using Blender game engine for a few years to learn Python and to build a few prototypes of various systems that I could use in larger future projects.

Lately I have spent time away from Blender to learn coding in general. I have studied Tkinter, Kivy and plain Python.
Along with that, I have studied PHP, Javascript, etc, etc.
I have also read several books and I’m still reading (which I can recommend to anyone who is interested in any language). For example even if you want to learn Python, you can read a book about C language. You’ll still learn anyway.

The purpose of this thread?
It got me thinking after reading and watching several speeches from professional programmers, that there’s a huge impact on what people who wish to learn programming see on forums as “nice tips” or “the right way”.

Shortened code
For example I have noticed a huge boom on “coding with the shortest lines”. Which as an idea may sound nice,
but soon turns out to be impractical.

The keynote when I start each programming book, I have noticed writing weighting out that we (coders) are writing documentation, instructions for computer. Computer doesn’t usually care what ever you write the short way or the long way.
So you are only hurting your self by doing so.

Commenting
I have now worked on a real application or a tool which client can use to update his website via user interface. I use Tkinter on this. After 400 lines of codes or so (which is really a ridicelously small amount of lines) I already noticed that how crucial it is to comment things. The lines you wrote yesterday will take a small time to get back up to speed,
unless you have commented them clearly. Also don’t be afraid of the “spooky empty white lines between codes”.
You’ll notice that keeping larger space between various things will keep things nicely organized to the eye!

Variables
What variable, where did I put it? When building even slighly larger projects I have found my self creating almost all variables prehand at the start of the code file. This way I know what variables I have and what their names are.
Only a few localized variables inside functions for “temporal calculations” I left out of this list.

[Mperonen]

reserved

[BluePrintRandom]

I tend to build and refine systems that use external logic triggers so the oop helps contain things in a way I understand, however I find I have label everything and explain logic to people, even if I document them…

I think one thing logic is missing is the ability to comment on a node in a dropdown… this would allow for documenting controllers sensors and actuator purposes and resonings so they evolve over time.

[sdfgeoff]

@BPR
This has nothing to do with logic.

There is a fantastic flow chart for coding, from the best webcomic ever: xkcd. Here it is:

It is true in so many ways. No matter your intention, code gets more and more confusing the more you write.

The solution is modularility and proper code design.
If you find a function called get_closest_object_with_property() you know exactly what it does, you can even guess it takes 3D position and a game property as parameters. After writing the function, you can then forget what goes on inside it. Button it up inside a generic bge functions module, and use it a million times without having to remember what it does or how it works.
Going along with this is the idea of docstrings. Ever noticed that in python you can type ‘help(max)’ and it will tell you what the function max does? (Notice it doesn’t tell you how it works, just what it takes as inputs, and what it outputs). Well you can do the same to your code using docstrings. Tripple quoted string at the beginning of a function to tell you what parameters it takes and what it returns.

So, what about comments. Quite frankly, I haven’t used a comment in a couple of years, and I can go back and, in a short space of time, figure out what everything is doing. Don’t get me wrong, comments can be useful, but sometimes it’s better to write a small function with a sensible name. So instead of writing #This part of the code does this’ and a couple lines later writing ‘this part of the code does that,’ split them into functions with sensible names. If it isn’t obvious what your code is doing without comments, consider restructuring it or using better variable names.

The other important thing is consistency. Pick a style and stay with it. If you use camelCase, use it for every variable. Same for under_score. I don’t care which, so long as it’s the same the whole way through.
The same goes for types of variables. In my code, the suffix tells me what a variable is. If it ends in a ‘s’ then it’s a list (ie item[s]), if it ends in a _vect, it’s a vector, or _dict, or, well, whatever datatype it is. This helps hugely with eradicating confusion when you try to iterate through a list of strings and discover you’ve just iterated through the characters of a string.

Something I haven’t mentioned here at all is code design. Design for things to be plug-and-play. Don’t use global varibles (as much as possible), as they mean the output of a function isn’t dependant on the parameters you pass to it. Use modules and imports to split code into obvious namespaces. Don’t use ‘from module import *’ as it leads to confusion about where code actually exists.

Finally, test each bit of code as you write it.
When I decide to make a bit of code in blender, I don’t start by writing a funtion, I start with a hello world. Then instead of printing a string, I make it print an objects name, and so I build it up and up (I don’t test every step, but…). I also often lay out the structure of my code, creating empty functions returning empty values and the working through them in turn.
Then you have to test your code. Test it for extreme cases, not the ones it was designed for.

[Monster]

I suggest to read the book “clean code”. It is very good and explains why a specific style works better than another (e.g. comments vs. descriptor names).

It also tells if 400 lines of code are good for a class or not (you did not mention where these 400 lines belong to).

[Kheetor]

I always wondered if you were Finnish as well considering your username

Yeah, I reckon it’s what we’re supposed to do. Luckily I’m not too much into programming as I’m into game development as a whole so often I just push the mess aside when it works and it’s not impossible for me to release something.

@sdfgeoff

So, what about comments. Quite frankly, I haven’t used a comment in a couple of years, and I can go back and, in a short space of time, figure out what everything is doing. Don’t get me wrong, comments can be useful, but sometimes it’s better to write a small function with a sensible name. So instead of writing #This part of the code does this’ and a couple lines later writing ‘this part of the code does that,’ split them into functions with sensible names. If it isn’t obvious what your code is doing without comments, consider restructuring it or using better variable names.

I’ve taken very similar stand. Nobody else is going to be reading my code as it’s not really something worth studying. Instead I write neat functions with sensible naming, and it’s practically as clear as reading a description of what it does. Commenting doesn’t really help me with the real problem of sometimes completely alienating myself from a project where I forget all the message i/o and the few globalDicts I was using at which point I have to study my own code and a bit and especially the object and logic setup a lot.

But if I was doing complex vector math with matrices for example I would want to comment it a bit because it’s not something that is easily readable to me and probably something I had to try many times to get right in the first place. Things that are not easy to describe in words either

@sdfgeoff

Finally, test each bit of code as you write it.
When I decide to make a bit of code in blender, I don’t start by writing a funtion, I start with a hello world. Then instead of printing a string, I make it print an objects name, and so I build it up and up (I don’t test every step, but…). I also often lay out the structure of my code, creating empty functions returning empty values and the working through them in turn.
Then you have to test your code.

This, I think is very important in getting somewhere with your programming. You can make even the most complex ideas work if you can figure out what little pieces you can build it out of. Getting each piece working is a nice incentive and when your grand scheme comes together the sense of fulfillment is rewarding.

On the other hand sometimes I’m working with something quite complex like inventory system. You have many modules and huge amount of functions you need to get in shape before you can test the thing in a meaningful way. I like the moment when you think “ok that should be it, I wrote about 200 lines of code just to get this thing draw something on screen.” Let’s hit “P” and start debugging! And then of course the first thing I find out is that I haven’t even yet typed in the name of my fresh module of code in the python controller I intended…

Test it for extreme cases, not the ones it was designed for.
I never do this and sometimes I need to revise large part of the code because I want to include some special case I hadn’t thought about earlier

[Goran]

Keep it simple: https://www.youtube.com/watch?v=JjDsP5n2kSM