[STICKY] Suggested C++ coding standards for UOX3

[Xuri]

giwo has a document up on http://www.sf.net/projects/openuo called UOX3 C++ Standards which contains some suggested standards for C++ coding styles/approaches for UOX3.

Feel free to comment or suggest additions/changes

[lingo]

I think it nice, But the uppercase filename is not good for *nix. Probably too late to do anything about it.

After looking through old news. I found another design document by Maarc http://darkangelab.freeservers.com/uox/UOX3Doc.html. Is it still what uox3 is aiming for?

[Xuri]

*nix has trouble using uppercase filenames?

As for Maarc's old design document, it was something Maarc started working on as a concept I guess - but as you can see it only touches on a few things, so it never really got off the ground.

[Maarc]

Crikey, I didn't even realise people could find a link to that old thing

I do have an updated version of it, it covers more ground (but still a dcoument from late 2003), which I guess I can post up if anyone is interested in seeing it.

As for what it was for, it was just my ideas and thoughts that I was throwing out there for dicussion, to see what people thought, what feedback there was (if any), and whether it would be useful to people. I've also had some other ideas since (about a year later), which dealt with trying to abstract the stuff some more (and I guess I've probably posted that around here somewhere too).

[lingo]

Xuri

No, *nix don't have problem with uppercase files. But since windows don't distinguish between cases, Sometime Windows developer won't pay too much attention to the filename when including them in the source files, and that cause problem in linux/bsd. But I worry too much, uox3 compiled just fine.

Maarc

I am very interested, and I intend to contribute to uox3. If you, or other developers won't mind, I am interest in discussing the issues.

[Maarc]

I'm sure any contributions would be more than welcome, it's always a positive sign to hear such things.

Here are the latest versions of my thoughts (but I haven't looked at them in a while, really)

1) <a href="http://darkangelab.freeservers.com/uox/ ... ml">Design stuff</a>
2) <a href="http://darkangelab.freeservers.com/uox/ ... tm">Global manager idea</a> - just a handful of notes about trying to create a few global managers, which could be implemented multiple times and selected at compile time (ie a txt based module, or a DB based module). Not plugins per say, just alternate implementations with a common interface

That second link also has a link at the bottom to the latest UML diagram I had been working on, as an idea/thought/rejiggering. It was created with ArgoUML.

Be warned, I haven't looked at any of it in 12 months, so I'm fairly sure my ideas would have changed since then. And they're not gospel by any stretch, I was just creating them as a point of discussion whereby people could come up with things, discuss, see if any is useful or not, or springboard to other ideas.

[lingo]

I am really not familiar enough with uox3 to comment, but here is my opinion base on my current knowledge.

Design
Source Code Restructuring
It what I would do previously, but my current thinking change a bit. I would only separate the code into separate directory if it can be compiled as stand along library. And if it still feel messy yet not able to stand on it own then I know the problem is really class coupling, the classes needs a refactoring first before directory separation.
Third party libraries is a definite plus. Why reinvent wheels .

Improved Class Hierarchy
definitely, I think uox3's main problems is too much coupling, If you see the uox3 doxygen files I created, uox3 files includes dependencies does not look good. But class refactoring can only be done safely after unit test completion. Unit test just make the regression test so much eaiser.

Object Factories
agree, I think this can be done first even before class refactoring.

Versioning
agree, very sensible.

You provides a lot of good sources and library that uox3 can use.

Global Managers
I really don't know enough to comment yet.

[Maarc]

One thing I can say is that the object factories have been included, that's about the only thing that did get included.

Previously, we had a relatively roundabout way of creating such things, relying on global arrays and all sorts of fun things (as you can imagine). But world object creation (NPCs, PCs, items, multis) get created through the ObjectFactory class now, which because of it's wrapping, means we can introduce more classes relatively easily.

Fresh sets of eyes can always bring things to the table that we might be too close to see.

The improved class hierarchy runs the risk of breaking worlds (depending on how it's handled).

And yeah, the code is highly coupled, changes can have a huge ripple-on effect.

[giwo]

I agree that the differing cases on the filenames can be a problem for *nix. But honestly I feel that NOT doing so is a bigger problem for everyone. In my opinion, it is much harder to read filenames, and thus get an immediate idea of what they are for. With 100+ files, especially with them currently in one directory, I think it's necesarry to have the upper/lowercase format.

On that note, however, we have gone out of our way to be case sensitive, ensuring this doesn't cause an issue for *nix users, and my plans are to continue that.

The idea of seperating out the sources into multiple directories has been tossed about for a while. Maarc and I have discussed it, EviL and I have discussed it at length, and others have discussed it here and in the UOX3 chatroom.

Ultimately it is something I would like to see happen, but even after doing it in its entirety, I wasn't satisfied. It is a two-edged sword to change such directory formatting. Firstly it causes all the makefiles and project files to be re-created. Moreover, it seperates things in a way that might seem logical to some, but illogical to others.

Contributions to the coding standards and outlook on UOX3's future are welcome and appreciated. If we don't know where we are going, how are we going to get there?

[Sydius]

I really like that design document, it is clean, easy to read, and has good advice.

I do not know if it belongs in that document or not, but the first in the list of “Practices to Avoid” reminded me of a neat trick my cousin taught me. One of the easiest-to-make bugs is a result of forgetting to type the extra equals sign, and cause an assignment instead of a comparison. Depending on what the code is doing, this may be very difficult to track down, or at best annoying. He gave the example of “if(a = 5)” and asked what the most intuitive way was to prevent that from happening, when you actually meant comparison. I scratched my head and said “I give up”, but the answer is pretty obvious: “if(5 = a)” – anytime you are doing a comparison with a constant, put the constant first.

I am sure you guys have thought about this before, but I just thought I would throw it out there anyway, since I was reminded of it.

[giwo]

That's a good idea, and I've actually heard it as advice before, but never had someone explain WHY they do it that way.

[Sydius]

One thing you may want to mention in that document, though, is that classes should make sure that constructors that are passed one variable are defined as being explicit unless it is intended to be used for implicit conversion (and in that case, a comment stating this should be there).

Also, I think that every class should either provide the otherwise compiler-generated operators (copy/assignment/comparison), disallow them by declaring but not defining them, or at least provide a comment stating that it was not overlooked and that the compiler-generated ones would be fine.

Returning a reference that is not constant should never be allowed, either, unless for a very specific purpose (such as for singletons).

The destructor of all potentially derivable classes should be declared virtual.

It might be worthwhile to have some kind of documentation on what exceptions might be thrown out of each function, too, and if the function is exception-safe or not (whether it will return the program to the state it was previously in (the best), leave the program in an undefined but valid state, or if it will leave the program in an undefined and potentially invalid state). Maybe just a comment above each function declaring which of the above it is.

Also, all objects (classes or structs) should always be passed by reference-to-const as opposed to being passed by value, unless there is a need for a copy. All trivial types should just be passed by value.

Might want to mention something about exposing private member data, too. Encapsulation is important, I believe, and that means no public variables.

Oh, and polluting the public namespace is a very bad thing to do – it would really be a good idea to start using namespaces more.

One more thing… you should never declare a variable until it is absolutely necessary to do so in a function. This is contrary to the way C and many other languages work, and some argue that all variables should be declared at the beginning of a function for clarity, but declaring them right before use not only speeds things up, but it also avoids many potential exception disasters, not to mention many argue that it is indeed more clear when a variable is declared near where it is used. The obvious exception would be objects used inside of a loop, those should be declared right before the loop.

Oh, and you should have a REALLY good reason for not using a shared_ptr instead of a built-in pointer.

[Sydius]

Oh, and you should use iterators whenever dealing with STL containers. This is so that you can easily change the type of container without breaking the code (so long as the new container supports the same kind of iterator used). Many very fast STL containers do not allow random access, so not using iterators makes it a pain to even try others.