🔒 Locked

Python Comments

Started by mikeman Jan 4, 2007 at 9:16 AM 1 replies 800+ views

Original Post

545

Jan 4, 2007 at 9:16 AM

For the last few weeks, I'm working on a 2D Platform/Action/RPG game in Python/Pygame/Opengl. Since it's getting big, and although I favour dynamic vs static typing, I figured that I need some kind of reminder about the types of the arguments in most functions. So I decided to document most, if not all, of them in a fashion like this:


def textured_rect(rect,tex_id,color):
    "(pygame.Rect,int,3*float)->None"


class ImageManager:
    ...
    def img_and_id(self,name):
        "(self,string)->(pygame.Surface,int)"
        return (self.images[name],self.tex_ids[name])
    ...

"3*float" means "a sequence(tuple or list) of 3 floats". Also, if the argument can be of any type, I just use "object" for its type. So I was wondering what other Pythonistas here think about this. How would you feel about a project that was written this way? Good,bad,annoying,redudant,useful? Any comments?

smr

174

smr

Jan 4, 2007 at 9:59 AM

Probably not a bad idea, but I don't see any reason to be so terse.

def textured_rect(rect,tex_id,color):    """Draws a textured rectangle       Arguments:       pygame.Rect rect: Where to draw the rectangle. The texture            will be stretched in order to fit the rectangle using            the current opengl magnification and minification filters.       integer tex_id: opengl name of texture to be used.        tuple (float, float, float) color: RGB color to be used to fill           transparent areas of the texture. Color component values           between 0.0 and 1.0. Values outside range will be clamped.       returns: None"""

I probably wouldn't go as far to dictate types, because python is a dynamic language. You're essentially static-typing by convention, with the convenience of not having to declare variable types explicitly to the compiler/interpreter. The user of the function shouldn't have to pass a pygame.Rect, as long as the object they do pass has the specific properties/methods that you need for the function.

mikeman

Author

545

mikeman

Jan 4, 2007 at 10:09 AM

Quote:

You're essentially static-typing by convention, with the convenience of not having to declare variable types explicitly to the compiler/interpreter. The user of the function shouldn't have to pass a pygame.Rect, as long as the object they do pass has the specific properties/methods that you need for the function.

Obviously, those "types" are not set in stone, they don't even represent a strict "rule". My plan is to use them merely as hints that help the programmer to have a pretty good idea about what the function needs with just a glance, without having to read a more extensive documentation. The fact that you can substitute "pygame.Rect" with any other type that supports the same methods is taken for granted of course since we're talking about Python, but if I'm going to write something in the comment, I can't write "an object that supports the attributes x,y,w,h and the method move()". Again, writing "pygame.Rect" does not mean you absolutely have to pass a pygame.Rect, as I said it's meant as just a little extra help to the programmer.

Topic Locked

This topic has been locked by a moderator. New replies are not allowed.