Miscellanous stuff

["Bjarke Hammersholt Roune" <asmild@post6.tele.dk>]

Hi! You probably have only a very dim recollection, if any at all, who I am. Well, my name is Bjarke Roune (as it probably says somewhere) and I'm a new part of the PenguinFile team. Well, ok "part" is perhaps a bit to large a word, maybe contributor is better. Hmm... Not really, as I haven't contributed much anything (yet, atleast). Hmm... helper, perhaps. No, I don't think I've been that much of a help either (yet). Well, anyway, as you can clearly see, I myself am a bit confused about my relationship with PenguinPlay, but I do watch what's going on, and I plan to be a part of the PenguinFile team, if that's possible.

 

Ahh, perhaps now you'll remember me in the future :)  "Oh, Bjarke, that weird guy" ;)

 

Anyways, watching PenguinFile, I have a few comments. The first thing is about your coding convention, or lack there of...

 

Some people do not realise this, but an API is also an User Interface, and just like with most any other thing that users (clients) needs to have people interact with it, the way the user (client from now of, further use of the word "user" will refer to players, not programmers) percieves this thing is what gets it sold (or, in this case, used).

 

Of course, APIs is somewhat of a special case, as the specifications and capabilities of an API is also very important. More so than with many other kinds of applications. However, that has for the last 20 years been changing slowly but surely. 20 years ago, the time of the programmer was far less worth than the time of the computer itself. This was because the processing power of computers was, to put it mildly, not very impressive, and the programmer user ratio was about 1 to 1, as usually the users WERE the very programmers who had created the programs. This, however, as I have previously stated, has been changing over the last 20 years.

 

As computers began to be more and more powerfull, and, most notably, smaller, the common man began to use them. These were the people who either just wanted to have them to see if they could learn to make them work (somewhat like many of us, I gather) and the few people who were unlucky enough to for some reason or other had to. Unlucky because using them was certainly not an easy task, and MOST certainly not for people who weren't interested.

 

Today, computers are as capable as ever, as small as ever, and almost everybody atleast knows the basics of using them (almost almost everybody I know; with the exception of one of my teachers who asked where the "rewind" button was on a discman :). More importantly (to API programmers), the user / programmer ratio has grown with a hast not seen in just about any other trade (driver / car manufacture people, sandwich eater / sandwich maker, violin player / violin maker etc.). This mean that programmers are in tremendous demand and the skilled ones are being paid very large vages (compared to other trades, especially the sandwich making one). Actually, making a piece of software today is very expensive (well, ok, a larger scale marketable ones is, not the kind thing you can create in a day or two), and the income generated by a program is not always larger than the expense of making it.

 

Yes, sure, that's all very fine, but why have you been dragging me through all this boring stuff, what's your POINT? You might ask. You know, the kind of thing people would like to get to when they've been very patient with the likes of you? Btw, do you like the way your teeth is arranged? That can easily be remodelled! You might continue, but probably not, as that would not be a very intelligent thing to say to someone over the net, as the action of remodelling the arrangement of other people's teeth is usually a thing that requires direct physical contact. With the exception of aggravating someone to the point of them chewing off parts of the table upon which they have situated their computer. Indeed, some people have been known to throw monitors out of their windows (not the software Window; in that case it would be the other way around), and a falling monitor is certainly a thing that atleast theoreticly should be able to rearrange the layout of someone's teeth. What if he was wearing a helmet and something to protect his teeth? You might object, but then again probably not, as that is a very stupid objection. Hmm... Your teeth still in place? Damn... ;)   (this should, if nothing else, atleast improve my recognisability factor: "Bjarke, oh, that weird guy that goes on and on about nothing at all")

 

Well, ok, I shall now give you the point, which you may already have guessed, considering the context. A programmers time is today worth much more than the time of a computer. That means that if a company can save a week or two by doing things one way instead of the other, that is usually what they will do. The quest is to minize the time that a project takes to fulfill. Things like complexity encreases this time, simplicity decreases it. Put simply; the less the programmer in question has to deal with, the faster he'll be churning out usefull and bug-free code. Something a programmer already knows about is much easier (and therefore faster) to deal with than something he doesn't. This must all seem pretty obvious to you, and not seem like very much of a point. And you would be interely correct. Because I haven't gotten to that part yet.

 

The point (for real, this time) is that it's a whole lot easier for someone who speaks English to understand someone who only speaks English than it is for someone who doesn't speak English at all. That was, however, not the point, only part of it. Expanding on that, it's also easier for someone to understand someone speaking English with a specific accent that this someone has already heard quite alot of before (watch some of CNN's interviews and comments, and you'll know what I mean) than it would be for someone who had never heard it before.

 

Now comes the point (really, I'm not pulling your leg this time, REALLY): PenguinPlay is suffering from a syndrome which I have just come up with: the CNN-syndrome. If you watch CNN, you will quite quickly realise that in many countries, what one would usually think would translates to "english", really doesn't, it translates to "something we like to call english, but as we haven't the slightest clue as how to speak it, we just gibber alot of words out really fast and let you try to figure out what we intended to say". Of course, CNN loves this, as they can then make the people they interview say exactly what suits them. CNN has even been known to re-use these interviews and make them mean completely different things.

 

Now, luckily, PenguinPlay is not CNN, which means the code in PenguinPlay is certainly not unintelligible, and the PenguinPlay programmers certainly *DO* have a clue on how to program C++. However, the specific ways in which they do this is about as varied as the people who appear on CNN. This mean that if a programmer from a real company looks over the PenguinPlay code in, say, 3 different places, he will see that those different places are programmed with 3 completely different coding conventions. This will very probably be interpreted by this programmer as a sign of unprofessionalism (someone might object that PenguinPlay IS unprofessional as there is no money involved. My response for someone with that specific objection would be for him to shut up, and that I felt perfectly fine and safe with the way my teeth was arranged, so he should just follow my advice and leave it at that).

 

Someone migth object that he shouldn't be looking through the source code, but rather the documentation (me, to take an example). My rebuttal would be that A) this is an open-source project, and he therefore probably would and B) Hmm... I forgot this one, just jump over to C) people who were actually interested in joining might make the same judgement.

 

Just about any real game developing company has some sort of coding convention that all emplyess have to know about and follow. Companies wouldn't do that if there wasn't a very good reason for them to do so, as it usually takes a little while for someone to get used to a new coding convention (it doesn't take too long though; not if it's intuitive), and during this transition period, the individual programmer will have more to deal with, thereby making him less productive. There quite clearly must be some kind of advantage. The advantage, of course, is that, in the end, he will have LESS to deal with, thereby making him much more productive in the long run, and, really, also in the short run, as it doesn't take that long to get used to a new coding convention, except if this run is extremely short, in which case he will not be more productive. "Extremely short" is not, though, the industry standard for runs, so I should be reasonably safe with my statements.

 

Now, on some of the teams in PenguinPlay, there are 6-7 people (?). It's not unreasonable that there will be atleast six times where one of these people will drop away and another will join. That means we have 14 people working on the same project at some time or another (perhaps more, perhaps less, I don't know). This means, with the current state of affairs, that we will also have 14 different coding conventions utilized within the same general area of code. This could get very, very ugly.

 

How many people will, at some time or another, contribute to PenguinPlay? 50? 100? 150? (if it runs over a year or two or more, this is not unreasonable, I think, but perhaps a bit over the edge; I don't now) That's 59/100/150 different coding conventions used within the same project (PenguinPlay). This could get *extremely* ugly.

 

An objection could be that as long as the name naming convention is used all over for functions, classes, members, macroes and anything global (in short, anything a client will have to interact with), there should be no problem. My rebuttal would be that, A)people will usually want to see what is behind going behind the scenes, B) it's not something that contributes to the image of PenguinPlay, C) it's also harder for PenguinPlay (us/you, whichever is most appropiate) programmers to understand each other's code D) it makes it harder for people to look through the code, and there therefore will not be as many constructive comments to it E) it's not only the guy who wrote a piece of code that will be maintaining it F) it promotes the line of thought that the different PenguinPlay teams are each completely running their own little game and there is no way the finished libraries will ever work together. Or, well, maybe not something that harsh, but atleast that the different libraries doesn't supplement each other as well as they actually do.

 

I think many people would perhaps object to F), but a coding the coding convention used in a project is very much also that part of that project's "feel", the spirit of the thing. If the coding convention of a project is unintelligible, a reader will also immediately at some level get the impression that the whole thing is unintelligible.

 

To put it simply, the coding convention utilized by a project reflects heavily on how people immediately percieve it.´If a person gets a bad first impression, that probably he will just look for something else.

 

Again, for programming companies, time is money, and money is the whole porpuse of the companies (atleast, a very large part of it; few are the companies that doens't want to make money...). Not following a well thought-out coding convention is detrimental to the ease of use of the whole package, and will therefore give both us/you and any programmers working for companies (yes, I realise that many of the PenguinPlay programmers probably also work for companies) more to deal with. This makes it take longer to create a game with PenguinPlay, and, indeed, PenguinPlay itself.

 

It also makes it harder for people to join and leave.

 

I think I have presented you with a reasonably comprehensive list of arguments for agreeing upon a well thoughout coding convention and then stick with that. I can, however, also think of a few arguments against doing that.

 

A) The part about agreeing itself. There are alot of people working on PenguinPlay. To get most of them to agree on ONE coding convention migth prove tricky, as it is forseeable that they will all try to promote their own specific coding convention. Taking into consideration the reputation that PenguinPlay has got for being a whole lot of talk, but no action, it might not be a wise idea to introduce suchs a controversial subject.

 

B) Right at first, it's not comfortable to use a different coding convention than one is used to.

 

These are both valid arguments. However B) is only a temporary problem. A), however, is another matter. It is far from an unsolvable problem, though. With a few agreed-upon rules for choosing the specifics of the coding convention, I think the problem will be minimal. In any case, the fact that a coding convention has not yet been agreed upon does not mean that no coding can take place, and even after the coding convention has been agreed upon, all code would not have to be redone right away. It would be sufficient if all new code was written with the new coding convention. As code was redone for other porpuses, the coding convention would then gradually begin to encompass all of the PenguinPlay. Of course, a little recoding for the only porpuse of the coding convention would be eventually prove to be nessecary, but if done gradually, this should be done big job, and changing the coding convention is quite easy.

 

 

Here is a draft of the rule which could possibly be used to agree upon a specific coding convention:

 

The coding convention should...

1. make it harder to make syntax errors, and make it easy to spot them. This also applies to bugs, thougth that is a hard job for a coding convention.

2. be intuitive and be resonably easy to learn

3. preserve horizontal space, while not being the least bit sparing with vertical space.

4. make it easy to spot what one is looking for, and make it easy to understand a piece of code at a glance

5. make it easy to find out what something is, and what it is not

6. make it harder to

7. be convinient

8. be adaptable so as to be able to deal with anything

9. be comprehensive, but still easy to memorize

10. be consistent

11. be true to the ideology of C/C++ (this migth prove to be a problem, as these can sometimes be in contrast with oneanother)

 

The argumentation against or for a specific proposed part of the coding convention should be based upon these 11 rules, and nothing else. So arguments like, "but, that's what most people do!" or "I'll never get used to that!" is not valid, as these kind of arguments will probably the kind of arguments that would be presented both for and against any proposal: most people think that what they've been taught or do is what most other people also has been taught, and everybody can get used to a coding convention, especially if it fulfills the above mentioned objectives. Consider it a lesson in flexibility and adaptability, two skills that are perhaps one of the most important skills you could ever have, nomatter which career you are pursuing.

 

Perhaps I should give an example on how an argumentation could be done for the possibility of introducing a full hungarian notation to PenguinPlay for built-in types.

 

The arguments against can be made in this way, based on the 10 rules drafted and outlined above:

 

** Rule 1

(make it harder to make syntax errors, and make it easy to spot them. This also applies to bugs, thougth that is a hard job for a coding convention.)

PRO(S):

In C, it is often nessecary to use void pointers and the kind, and many serious memory-corrupting bugs can potentially arise out of mistaking the size of a variable.

 

CON(S)

It will make variable names longer, and it will require one to remember both the name and type of a variable to correctly spell it's name. This can introduce many syntax errors.

 

** Rule 2

(be intuitive and be resonably easy to learn)

PRO(S)

It is intuitive to use this system, as it is intuitive to know what kind of variable you are working with.

 

CON(S)

It is harder to learn this system, as pre-fixes or post-fixes has to be learned for all types to which it applies. It is not intuitive to be SO specific about the types of variables.

 

(this is an example of both arguments beeing equally correct; "intuitiveness" is often quite subjective)

 

** Rule 3

(preserve horizontal space, while not being the least bit sparing with vertical space.)

PRO(S)

None.

 

PRO(S)

This system make variable names longer, thereby using extra horizontal space.

 

** Rule 4

(make it easy to spot what one is looking for, and make it easy to understand a piece of code at a glance)

PRO(S)

Knowing what types of variable one is working certainly make it easier to understand code, especially if the code will work for some types of variables, but not for others.

 

CON(S)

This system makes all variable names longer, which takes up horizontal space and clutters up the code. This is higly detrimental to understanding the code at a glance.

 

** Rule 5

(make it easy to find out what something is, and what it is not)

PRO(S)

This system certainly makes it *MUCH* easier to know what variable are, and what they are not.

 

CON(S)

This level of explicitness is overdoing it, and is not nessecary.

 

** Rule 6

(be convinient)

PRO(S)

This system makes many of the looking for the declaration of a variable to get its type unnesecary.

 

CON(S)

This system is HIGLY inconvinient. Not only do you have to append something to each and every variable name it applies to, you are also in DEEP trouble if you suddenly chose to change the type of a variable, as that completely breaks all of your code that uses this variable.

 

** Rule 7

(be adaptable so as to be able to deal with anything)

PRO(S)

 

CON(S)

Changing the type of a variable breaks existing code. The system only applies to some types.

 

** Rule 8

(be comprehensive, but still easy to memorize)

PRO(S)

The few pre-fixes or post-fixes are easy to learn

 

CON(S)

There is more to memorize with this system than without it.

 

** Rule 9

(be consistent)

PRO(S)

 

CON(S)

The system does not apply to all types.

 

** Rule 10

(be true to the ideology of C/C++ (this migth prove to be a problem, as these can sometimes be in contrast with oneanother))

PRO(S)

This system is true to the C ideology, as C is very much conserned with the programmer remember the types of his variables and allocations, as these will often lose or change type.

 

CON(S)

This system is true to the C++ ideology, as the diverse and rigorously applied type-correctness features of C++ will make it very rare for a variable to lose it's type. And with derivation, one type might actually also be any number of other types, thereby making this system somewhat pointless.

 

 

These are the kind of arguments that could be represented. I here had to only take one rule at a time, so some objections could not be made to some of the arguments, because those objections would belong to a different rule, but the this rule system will not be as cumbersome or restrictive when applied, as there is normally no suchs requirement. You also wouldn't actually have to remember the rules, but it's nice to have them, in case of one specific issue getting a little over-heated.

 

If there is one side for, and another against, a proposal, and they seem to be somewhat equally large and have argumnets that are equally good when judged by the rules, I would not recomment a majority vote, but rather flipping a coin or something. (people have to trust the man doing the flipping then, though... :) If the arguments are really equally good from both sides, it doesn't matter anyway, and flipping a coin will hopefully make the losing side not feel like they've been trated unfairly. Notice that these rules are just a draft, I'm not saying it has to be this way. It would probably also be a good idea to have a general outline of which rules are the most important, so as to more effectively decide on which conventions to use.

 

Making code conform to a specific coding convention would give all the benefits I've lined out above, and I believe I've given reasonably good solutions or answers to all the problems introducing suchs an innovation would cause. If you can think of other major problems with doing this, then I'd be interested in hearing them.

 

IMHO the disadvantages pale in comparising to the advantages.