GP32 Who here likes to design?

[generalnmx]

Lemme give you a sample from GPFM (parts of which I am reusing):

void ShowImageView(void)
{
	char szText[80];

	if (gpDrawMode == VIEW_FIT)
	{
  GpFill(0, 0, 321, 241, 0x00);
  PutFitPage(gpViewImage, gpDrawCount);
	}
	else if (gpDrawMode == VIEW_DESKTOP)
	{
  if (gpViewImage->Width < 320 || gpViewImage->Height < 240)
  	GpFill(0, 0, 321, 241, 0x00);

  PutDesktopImageOffset(gpViewRight - gpViewCol, gpViewBottom - gpViewRow, gpViewImage, gpDrawCount);
	}
	else
	{
  if (gpViewImage->Width < 320 || gpViewImage->Height < 229)
  	GpFill(0, 0, 321, 229, 0x00);

  PutImageOffset(gpViewRight - gpViewCol, gpViewBottom - gpViewRow, gpViewImage, gpDrawCount);
  GpFill(0, 229, 320, 11, COLOR_MAGENTA);

  // Line count
  GpTextOutXY(4, 229, gpImageViewFileName + 3, 0x0f);

  gm_sprintf(szText, "%dx%dx%d [%3d]", gpViewImage->Width, gpViewImage->Height, gpViewImage->BPP, gpViewAccel);

  GpTextOutXY(310 - (strlen(szText) * 6), 229, szText, 0x0f);
	}
}

What do those functions do? Can you easily determine from the onset? You probably won't be surprised to know, that the headers don't have any prototype information. Anyone looking at this code basically has to run through and figure it out for themselves.

No, I don't need help understanding this code (now, anyway). It just frustrates me to see this type of behavior in aspiring, and even worse, current developers. Why do the best coders seem to shy anyway from even the most minimal documentation?

I am not putting the author of this code on a crux (especially since I don't even know their name, as it was not available anywhere I could find). In fact, it may be unfair of me, as I believe English is not the author's native language. I am just using this code as an example. I truly have deep respect for this author's coding skills.

Here is a sample of my code for comparison. Please bear with me.

/* Setup a new TileMap with given maximums */
void0 IGameMapInit(ubyte8 width, ubyte8 height)
{
	int32 y, x;
	if (width <= MAP_MAX_WIDTH)
  eMapWidth = width;
	if (height <= MAP_MAX_HEIGHT)
  eMapHeight = height;

	eTileMap = (TILEINFO2DARRAY)ISystemMemoryAllocate( sizeof(TILEINFO) * (eMapWidth * eMapHeight)  );
	for (y = 0; y < eMapHeight; y++)
  for (x = 0; x < eMapWidth; x++)
  {
  	eTileMap[x][y].tileNum = rand() % 3;  	/* cannot be greater then MAX_TILENUM */
  	eTileMap[x][y].blendTileNum = MAX_TILENUM;  /* means no blended tile here */
  	eTileMap[x][y].bgSpriteNum = MAX_SPRITENUM;  /* means no sprite located here */
  	eTileMap[x][y].ptrSpriteNum = NULL;    /* means no player sprite located here */
  	eTileMap[x][y].SpriteRow = 0;
  }
} /* end of IGameMapInit() */

While I admit that I may like its format better, I cannot say it represents the "best" design. Nor can I even generalize by saying it is a "good" design. Really, design in C may seem rather silly since it's a functional language, but I think at least some practices should be upkept. At least documentation. Here are my minimal expectations: Everything not intuitive has a short blurb about its purpose. That covers from function prototypes to what "#DEFINE __MOOGAR__" is for. Then the question is, what should be considered "intuitive"? Perhaps you think everything is intuitive and nothing needs comments. I think you're wrong, but maybe I'm wrong. I think comments and design should be tackled from the perspective that people other than you may be viewing your code. If it isn't documented somewhere else, than you should do it.

Really, I'm not here to bitch about other people's habits and styles. I am just curious. Maybe I am wrong about what I consider "good design". For those that want to know my personal views with C (and not just what I consider minimum expectations for everyone), here they are:

- Anything I think is not intuitive should be labled appropriately. (can you guess what "void0 IGameDiamondMove(POINT *pt, ubyte8 dir)" does or the variable "SPRITEINFO.SpriteRow" is for?)

- All function names should start with the name of the header they originate. (Example: AccountsDatabaseLoad from accounts.h), UNLESS they are a utility function for a simple structure, in which case it should start with the name of the structure, followed by an underscore.

- All functions names should start with a capital letter and capitalize each word in the name (example above).

- No underscores in function names UNLESS it is a utility function for a structure.(in C++ you don't have this problem because you can overload operators inside classes). I know you can add pointers to functions inside of structures, but I don't want to add more space requirements then necessary.

- In the case of actions upon an object or entity, function names should be organized like this: AccountsDatabaseLoad instead of AccountsLoadDatabase (this is because of insisting on the "Accounts" addition). "Database" is the entity here, so "Load" should be an action upon that entity (a subset). "All the functions that load something" doesn't sound as good as "Functions that manipulate the Database entity". An example with multiple subsets (besides "Accounts") is "AccountsDatabaseInputParse" instead of "AccountsDatabaseParseInput".

- All ending scopes more then a decent amount of characters should explain what they are ending (like "} // end if" ). Always do it at the end of functions, and at the end of scopes less then three lines apart.

- else statements should have a little blurb explaining what condition they are specifically designed for (possibly just the negative of the if statement)

- Variables should not contain any underscores. Instead of "map_width", use "mapWidth". When adding attributes (like "e" for extern'd or "b" for boolean), it should look like "eMapWidth" or "iMapWidth" (where "i" means "integer").

- Everything that is "externable" (allowed to be used in other files, but declared locally), should have an "e" before the name.

- #defines should always be ALL caps. #else and #endif should follow the same rules as else and ending a scope. #defines that are used as "options" for compiling (such as using certain code) should have two underscores preceeding it (ie, "#define __BLAH").

I'm getting sleepy so I'll stop here (I worked on this post off and on), but I think that's all of it. I want to remind everyone reading up to this point that I, in no way, expect anyone to follow all of these rules. They're just the way I like things. Maybe my design is confusing to other people, or cumbersome. I'd also like to know if you feel that way.

Oh, and if you're wondering why anyone can type so much, I can type around 70 WPM or even higher. I don't use the "Home Key" method, so I have never gotten carpel tunnel syndrome from any position, yet my WPM is kinda variable. The highest I sometimes go up to is 100 WPM. Maybe this also has something to do with me not caring how long a function name is (as long as it is less then 15 letters, or an alt is given of course).

 

[woogal]

I agree with many of the points you make, although I don't do most of them myself . I think the two code examples you gave are very bad however (as examples, not code). Your code does need comments (and uses them very well) because what the code is trying to acheive isn't obvious as it is unique to your application. The GPFM code on the other hand doesn't need any comments (or hardly any comments) because a) the objective is clearly to do with images and people understand the attributes an image has (width, height etc) and B) All function and variable names are very clear in what they are/do (gpDrawMode, ShowImageView, gpViewImage->Width etc). The GPFM code sample is very neat and tidy and self explanatory and is exactly what good code should be - self documenting.

For those of you wondering, my own code is neither self documenting or full of comments which is why none of it has been released yet I will get round to tidying it up soon. I promise

 

[Squidge]

I like self-documenting code, and the parts that are not self-documenting are normally well commented.

However, sometimes, it just takes too long, so for test projects and ways of finding out how something works (like how to talk to SMC cards reliably via the hardware registers), then I normally write pretty crappy code which is just thrown together. However, once I have a basic understanding of how everything works, it gets scrapped and rewritten.

In code that is not test code/see how it works code, I would never use variable names like "x", "y", "width", but rather prefix the variable name with the type fo variable it is, so it would be "iY" and "iX" to signify they are ints as the code is being written, etc.

 

[giffel]

There always seem to be people bitching about code instead of being happy with what
is released. I think exactly these people are a good reason never to release any code to
the public. Most projects start because of a personal need and will end whenever this need
is fulfilled. So dont expect people to clean up/include more features after that, simply
because that would be no fun. It would be like an unpaid job. Of course, some people live
of the recognition they get for that work from others, but many may just have moved on
or got a life.

 

[Rico]

Well I tend to either write code for everyone or myself. If it is myself, I'll only include small hints. If I ever abandon the code I won't be able to go back to it, sure, but that doesn't matter.

These guys are writing code for themselves, not everyone, and saw so need to keep a good design methodology. They open-sourced it out of generosity. Unfortunately, "beggars can't be choosers". However, for the sake of your own understanding of the code and to make it easier to add to or port, consider adding some standard formatting rules to your code.

 

[motten37]

Hmm - comments, naming-conventions etc. have absolutely nothing to do with design.

You may have a wonderful design implemented poorly w/o comments and so forth just as easily as you will see poor or non-existant "designs" coded neatly with comments etc...

I agree though - having to wade through other peoples undocumented code (which I do daily at work) can be frustrating to say the least. But we can't really make demands regarding stuff that's done for >free<, and I'd take undocumented gp32 code instead of nothing any day.

Regarding comments I find that commenting sometims helps me express complex ideas more clearly. I.e. sometimes I'll write complicated nested stuff purely in comments / pseudocode / natural language so I can do it >fast< and then implement it afterwards. This way I don't get bogged down with details in the initial pass. As an added bonus I'll know what I was thinking when I need to bugfix or update it half a year later and my colleagues won't have to bug me so much if they take over the project ;-)

Cheers

/motten

 

[generalnmx]

There always seem to be people bitching about code instead of being happy with what
is released. I think exactly these people are a good reason never to release any code to
the public. Most projects start because of a personal need and will end whenever this need
is fulfilled. So dont expect people to clean up/include more features after that, simply
because that would be no fun. It would be like an unpaid job. Of course, some people live
of the recognition they get for that work from others, but many may just have moved on
or got a life.

I just want to make sure everyone understands how deeply respectful I am of those who do release their code publically, in any capacity. Without their help, I wouldn't have gotten as far as I am as fast as I did. Mostly I was just curious as to people's opinions. And yes, I agree it is not fair to display someone else's work which was just released publically out of the generosity of its author. I apologize to anyone I offended.

The GPFM code on the other hand doesn't need any comments (or hardly any comments) because a) the objective is clearly to do with images and people understand the attributes an image has (width, height etc) and  All function and variable names are very clear in what they are/do (gpDrawMode, ShowImageView, gpViewImage->Width etc).

Well it wasn't obvious to me until I ran through all of the code (not just that piece) several times, but maybe I'm just stupid. Otherwise, this is an example of where "self-documenting" may be sufficient to some people and not sufficient to others.

Hmm - comments, naming-conventions etc. have absolutely nothing to do with design.

Not according to my professors But really, it depends on what you define as "design". I was taught (and believe) it encompasses all levels leading up to the implementation, not just the coding itself. Just people most independent coders merge all these levels together, doesn't mean it's not valid. But, just to be safe, I changed the poll's name.

 

[MojoJojo]

I find if I carefully plan out a section of code, I tend to comment it well. But then I rush other bits just to get it to a state where I can begin testing, with the intention of doing it properly later. Of course, that stand in code often ends up becoming the main code...

Does/did anyone use Hungarian notation? (Uh, I think that's what was called). Big craze for it in the 90s, but people don't seem to care anymore. It was horrible, I remember, and I'm sure Microsoft pushed it only to help obfuscate their operating system.

 

[Rico]

Yeuch. I hate Hungarian notation. That's if you mean stuff like m_piCount for pointers to ints which are private members of a class. Developers don't need to be spoon fed, most IDEs will give you adequate info on variables and functions and the rest you can remember.

 

[Takashi]

People tend to forget that comments are wonderfull tools for a coder to relax:

(this appears after comenting around 30 or 40 descriptions simmilar in style)

// NOP - No Operation. The opcode is EA - "It's in the game"(tm) :p
void NOP();

// ORA - OR Acumulator with memory. I like AND better ^^;
void ORA_D8(Uint8 value);
void ORA_D16(Uint16 value);

// PEA - Push Efective memory Adress. It's also used to make soup.
(etc...)

To clarify completely obscure commands:

E = 1;  	//Start in 6586 emulation mode. Kinky.

But in fact, comments are a tool for the author to solve his own mess of a code, if he picks it up at a later date:

mpos = 0x4300 + (bit << 0x02); // Get base DMA fetch info
/* Now, we can get the rest of the info staring from 43x0*/
stats = GET8(0x00, mpos);       // General modes
regpipe = GET8(0x00, mpos+1);   // What $21xx register is being used
startpos = GET16(0x00, mpos+2); // Transfer relative to mem pos xxxx
bank = GET8(0x00, mpos+4);      // at the bank xx
size = GET16(0x00, mpos+5);	// Transfer xxxx bytes
if (size == 0x0000) size = 0xFFFF; // Read qwertie's doc

I too had classes of code design... But in heart, I'm still a BASIC spaggeti-writer. When I comment, I do it only to preserve sanity and for myself. Most people write code thinking "I'll remember what this does", and 3 years later, they have a foreign file they know nothing about. Also, after failing a class just because the teacher didn't think my comments were clear enough taught me the lesson - Never include weird remarks in your comments(1). Er, I mean, allways be explicit of what you did to the code, even if it takes some explaining:

// Ths new version of execpu.c is quite diferent of the original 
// one. Notice a FETCH instruction that optimizs PC use.
// Maybe this way the stack consistency problems will be solved. 
// These changes also bring all the CPU functions into the execpu.c
// core. Lacks the initialization, tough (ie. initial SP, setting B).

If people are really serious about using comments as means of effective documentation, I'd suggest something like doxygen that introduces strick-ish rules to sutch methods, and usefull, navigable content from all the work from commenting.

Er, I just wanted to raise my post count. It's 6am over here, you know.

(1) - I added a comment in the line of "release the winged apes!" in a comment line related to a error routine. Teacher reasoned it wasn't clear enough what it called for.