am I documenting correctly?

Here is a page of code for my “Marble Madness” style game I am working on. I was wondering if you fine ladies and gentlemen could tell me if my documentation needs improvement.

import bge
import GameLogic
import pprint
import time
import mathutils
import Rasterizer
from math import sqrt

cont = bge.logic.getCurrentController()
scene = bge.logic.getCurrentScene()
own = cont.owner
g = GameLogic

# slow speed for not using CTRL
slow = 250
# fast speed for using CTRL
fast = 500

velocitymax = 10.0

# for debugging
x = own.worldPosition.x
y = own.worldPosition.y
z = own.worldPosition.z
start = [ x, y, z]
end = [ x, y + 10, z]
isballtouching = False

#equation for diagonal movement force
dslow = ((sqrt(2)) / 2) * slow
dfast = ((sqrt(2)) / 2) * fast


def movement(cont):
    
    # direction keys
    keyw = cont.sensors["w"]
    keys = cont.sensors["s"]
    keya = cont.sensors["a"]
    keyd = cont.sensors["d"]

    # fast movement key
    rightctrl = cont.sensors["rightctrl"]

    forcemove = cont.actuators["forcemove"]
    floorsensor = cont.sensors["floorsensor"]
    
    # is the ball tounching the floor?
    if floorsensor.positive:
              
        if keyw.positive:
            
            # fast
            if rightctrl.positive:

                # diagonal Movement
                if keya.positive:
                    
                    own["dampingon"] = False
                    forcemove.force = [-dfast, dfast, 0.0]
                    cont.activate(forcemove)

                elif keyd.positive:
                    
                    own["dampingon"] = False
                    forcemove.force = [dfast, dfast, 0.0]
                    cont.activate(forcemove)
                
                # straight movement
                else:
                                                
                    own["dampingon"] = False
                    forcemove.force = [0.0, fast, 0.0]
                    cont.activate(forcemove)

            # slow
            else:

                # diagonal Movement                
                if keya.positive:
                    
                    own["dampingon"] = False
                    forcemove.force = [-dslow, dslow, 0.0]
                    cont.activate(forcemove)

                elif keyd.positive:
                    
                    own["dampingon"] = False
                    forcemove.force = [dslow, dslow, 0.0]
                    cont.activate(forcemove)

                # straight movement                
                else:
                                                
                    own["dampingon"] = False
                    forcemove.force = [0.0, slow, 0.0]
                    cont.activate(forcemove)    
                    
        elif keys.positive:

            # fast
            if rightctrl.positive:

                # diagonal Movement
                if keya.positive:
                    
                    own["dampingon"] = False
                    forcemove.force = [-dfast, -dfast, 0.0]
                    cont.activate(forcemove)

                elif keyd.positive:
                    
                    own["dampingon"] = False
                    forcemove.force = [dfast, -dfast, 0.0]
                    cont.activate(forcemove)

                # straight movement                 
                else:
                                                
                    own["dampingon"] = False
                    forcemove.force = [0.0, -fast, 0.0]
                    cont.activate(forcemove)

            # slow
            else:

                # diagonal Movement                
                if keya.positive:
                    print("keya.positive")
                    own["dampingon"] = False
                    forcemove.force = [-dslow, -dslow, 0.0]
                    cont.activate(forcemove)

                elif keyd.positive:
                    
                    own["dampingon"] = False
                    forcemove.force = [dslow, -dslow, 0.0]
                    cont.activate(forcemove)

                # straight movement                 
                else:
                    print("keys.positive")                            
                    own["dampingon"] = False
                    forcemove.force = [0.0, -slow, 0.0]
                    cont.activate(forcemove)

        # straight movement to the left
        elif keya.positive:

            # fast
            if rightctrl.positive:
                                                
                own["dampingon"] = False
                forcemove.force = [-fast, 0.0, 0.0]
                cont.activate(forcemove)
            
            # slow
            else:
                
                own["dampingon"] = False
                forcemove.force = [-slow, 0.0, 0.0]
                cont.activate(forcemove)

        # straight movement to the right
        elif keyd.positive:
            
            # fast
            if rightctrl.positive:
                                                
                own["dampingon"] = False
                forcemove.force = [-ast, 0.0, 0.0]
                cont.activate(forcemove)
            
            #slow
            else:
                
                own["dampingon"] = False
                forcemove.force = [slow, 0.0, 0.0]
                cont.activate(forcemove)
        
        # no direction keys being pressed, but touching the floor
        else:
            
            own["dampingon"] = True
            cont.deactivate(forcemove)
    
    # no direction keys being pressed and NOT touching the floor
    else:
        
        own["dampingon"] = False
        cont.deactivate(forcemove)        
        
        
# changes maximum velocity depending on wether or not the ball is touching the floor
# zero maximum velocity when ball is not touching floor        
def velocity(cont):

    forcemove = cont.actuators["forcemove"]
    floorsensor = cont.sensors["floorsensor"]
    
    # for debugging        
    x = own.worldPosition.x
    y = own.worldPosition.y
    z = own.worldPosition.z
    start = [ x, y, z]
    end = [ x, y + 10, z]
        
    if floorsensor.positive:

        own.linVelocityMax = velocitymax
        Rasterizer.drawLine( start, end, [ 0.0, 0.0, 1.0])
    
    else:

        own.linVelocityMax = 0.0
        Rasterizer.drawLine( start, end, [ 1.0, 0.0, 0.0])


# translation damping
def damping(cont):

        
    # Lower values equals greater damping        
    own.worldLinearVelocity *= 0.90
    
    #own.worldAngularVelocity *= 0.95 for rotational damping
    


maybe copy and paste into blender to view it easier with all the color formating.

Seems clear to me :slight_smile: I like long explicit names for variables and comments to understand the general picture of the code. Thus I’m happy.