code interface specifications

[Maz]

Edit: Originally posted in Game Design, where it was off-topic. Moved here by Geoff /Edit

Well, this post is really not an design post either. But since you were talking about interfaces, I decided to post my thoughts in here too.

For a newcomer like me, it would be great to see some kind of interface specifications - and I am talking about function interfaces for different systems.

a simplified example:
Let's assume I am programming an engine to display a thermometer. I could have functions like:

Code: Select all

/**
*\brief Function to initialize termometer system for use. 
*
*    Must be called before termometer-component can be used.
*
*    @param
*    @returns true if success, false if fails
*    
*    @see termometer termometerUninitializeEngine()
*/
bool termometerInitializeEngine(void);

/**
*\brief Function to set temperature. 
*
*    Can be used to set temperature. If temperature which is not between TEMP_MAX and TEMP_MIN is given, call is ignored, and 
*    warning is being printed in log file.
*
*    @param int temperature        Numerical value for temperature.
*    @returns previous temperature
*    
*    @see termometer termometerSetWarming()
*/
int termometerSetTemperature(int temperature);

/**
*\brief Function to set temperature to fahrenheit or celsius scale. 
*
*    Default scale is set to be Celsius.
*
*    @param ETermometerScaleType scale      can be ETermometerScaleType_Celsius or ETermometerScaleType_Fahrenheit
*    @returns true if success, false if fails
*    
*    @see
*/
int setScaleType(ETermometerScaleType scale);

That would ease newcomers life Besides, if this was done, then almost anyone who's capable to writing code could implement pieces. (After all, you already have requirements. When requirements and interfaces are known, well, rest is just implementation and testing.) Naturally this would also allow more accurate testing...

I know this sounds like hard work, but it really is worth the time used. Naturally the most important things are things which are going to be used outside of 'termometer component'.

If the doxygen syntax is used, then these comments can be in header files, and readable documentation can be produced && displayed in web (as html) && offered for download as pdf.

[Geoff the Medio]

There seems to be two issues here: documentation of the existing interface of objects, and specification of interfaces of classes and game systems that haven't been implemented yet.

Regarding documentation, there already is fairly thorough documentation of the public interface to objects in the C++ headers, and partial documentation of private interface when deemed necessary. This isn't formatted as formally (no @param or @returns) and generally isn't as lengthy as you've suggested (it's often all on one line, in a comment after the function declaration). All the relevant information is usually there, and in most cases, particularly simple getters and setters, one line is enough. And in more complicated cases that need a longer description, a multi-line description appears before the function declaration.

Doxygen does a reasonable job with this, putting the appropriate comments with with each function.

Regarding specifying the interface for classes or functions that have not been written yet... Figuring that out is half the job of doing the coding. It's just not going to happen for the majority of classes and functions that need to be implemented. If you have a specific feature of the game design document or programming work page you'd like to work on, but don't want to figure out the interface for, then I might be able to work something out, though...

[Maz]

Regarding specifying the interface for classes or functions that have not been written yet... Figuring that out is half the job of doing the coding.

Yes, it indeed is. And often it is the most crucial job. I'll post some more thoughts regarding this later..

[Maz]

Later is now when I am again at my peacefull work place (When I wast writing the previous reply, I had a crying newborn on my arms - it is nasty when 1,5 months old child has a flu )

Allright, I bet most of this is well known by you, but I'll just write this anyways.

Well planned interfaces are crucial. They allow (at least) next things:

1. Easy and meaningfull ways to use features.
- This is quite obvious, if we wish to set temperature in my previous example, it is convenient to use a function which takes the new temperature as parameter, and returns success code someway. It would be less convenient to do this via some ridiculous IF, like

Code: Select all

/**
* \brief function for getting pointer to termometer temperature value
*/
int* prepareTemperatureChange();
/**
* \brief read new value from temperature storage
*/
void applyNewTemperature(void);

And the most horrible way would be to have a global variable helding this value...
2. Easier modification of code.
- When interfaces are planned cleverly, we have managed to divide the code in reasonable blocks. This is half of the job for having maintainable code.
3. Avoiding collisions between components.
- When each interface is planned and shown, we automatically have a list for most variables, namespaces, functions etc.. Although with proper C++ this is not such a huge issue. (forgive me for providing this dull points, I do have worked more with C)
4. Easier understanding of code.
-Well, the temperature example in section 1 should explain this

That's why I believe that the most of the interfaces should be planned by ones who do the best job (I am not pointing at anyone, nor am I accusing anyone, I do not have right to do so (I am quite green myself, and I do not know you guys [yet])

And why beforehand?

Because.
1. That would allow planning the future features in beforehand.
2. That would give newcomers easier starting point. It is far easier to do a component when one says:
"Please write temperature showing system which creates these function/message interfaces:
func1()..
func2()..
func3()..
msg1...
msg2...
And fulfills these requirements."
instead of having a task:
Here are the requirements, here is the code, you could for example do that temperature part...

I understand how big task it is to create the interfaces. I also do know that it is hard to make them 100% working at first try. But that's what writing code is, it is re-doing things. However, changes in interfaces are the most nasty changes, which (in my opinion) just makes the need for well planned IFs even more important.

I hope you guys do not feel like I have come in here just to tell you that "you are doing wrong, you should do it like this". I know most - if not all - of you are propably much more experienced than I. I just wanted to give another point of view. I am not expecting you to change your ways just because one newbie is creating s*loads of posts nagging about things But perhaps you wish to consider my words?

Ps. I installed FC8 at home, it is just that now I have problems with my USB WLAN stick's drivers... It seems like the new rt2x00 driver has some problems with handling IRQs. :/

[Geoff the Medio]

The first half of your post is an argument for encapsulation and modularity. And yes, these things are good, so I'm not sure what your point is when posting them...? Having a discussion about it is fine, though seemingly a bit off topic... Regardless, they are not really issues of planning, but rather are qualities of good interfaces, which can be achieved to a large degree by adding parts as you go, refactoring when necessary, and being sure to keep the parts modular and properly encapsulated.

The second half argues for interfaces to be coded up, or at least documented, as much as possible as soon as possible. And yes, this would be nice. But as noted above, isn't likely to happen for most tasks that need doing any time soon.

But, as also noted above, if you have a specific feature you're interested in implementing, and would like me to set up the classes and/or function declarations you'll need to fill in, I can have a go at it, or at least we can discuss it as you try to work out something reasonable yourself.

[Maz]

I am sorry for being confusing with my posts. I just get a bit carried away when I'm typing.

The first half of your post is an argument for encapsulation and modularity. And yes, these things are good, so I'm not sure what your point is when posting them...?

Regardless, they are not really issues of planning, but rather are qualities of good interfaces, which can be achieved to a large degree by adding parts as you go, refactoring when necessary, and being sure to keep the parts modular and properly encapsulated.

That was my point. Point was that interfaces are perhaps the most crucial parts in program, and thus they should be well planned, specified and as much fixed as possible. And that's why those should be done by the best persons here. (this was the point in the first part of my post).

And thank's for the offer about creating the IF for me. I will surely ask you to do it or for help, if I ever get to do something At least I believe I'll have new enough boost libraries on my machine now :rolleyes: . If only I got the network working...

This post was just to explain why I did previous post :rolleyes: That's what it is when you do it badly at first time...