Changes between Version 4 and Version 5 of PadawanPitfalls


Ignore:
Timestamp:
01/04/08 14:16:47 (13 years ago)
Author:
tim
Comment:

Typos and grammar

Legend:

Unmodified
Added
Removed
Modified
  • PadawanPitfalls

    v4 v5  
    1010   If your initialization fails for any reason and you have to throw an exception, make sure that before throwing the exception you cleanup all the resources claimed and you unregister you thread from any facility that you registered it for (for example from the Fawkes Network Hub). The reason for this is that `finalize()` is not called in that situation (if the thread does not get started), and in the destructor it is not safe to destroy the resources because you don't know if or when `init()` failed. 
    1111 `finalize()` may not throw exceptions: 
    12    Catch exceptions in `finalize()`, log the error and then go on with finalization. Since your thread is about to be stopped anyway you should finalize all you can, if there is an error log it and go on, do not stop the finalization after only half of it is done just because on step failed. 
     12   Catch exceptions in `finalize()`, log the error and then go on with finalization. Since your thread is about to be stopped anyway you should finalize all you can, if there is an error log it and go on, do not stop the finalization after only half of it is done just because one step failed. 
    1313 Free resources in `finalize()` claimed in `init()`: 
    1414   Any resources you claim in `init()` have to be freed in `finalize()`. For example close all BlackBoard interfaces that you opened, unregister from any facility you registered for etc. 
     
    1616== Logging == 
    1717 Log as much as needed, and as little as possible: 
    18    Logging is a good thing in general, it helps to find bugs and to locate problems while running the software. But for two reasons it is a good things to use logging only sparsely: firstly logging is an expensive operation. Even if it is not that expensive, it's still extra work and consumes resources (IO is in general not that cheap because it is rather slow compared to everything else your plugin can do). Secondly if there are too many trees you don't see the forrest. This means that if you log too much the important stuff goes unseen. Thus report errors, and sparse special events that are good to now and happen rarely (like loading a plugin), log as much as you like during the development phase, but at a tournament make your application to shut the f*** up. 
     18   Logging is a good thing in general, it helps to find bugs and to locate problems while running the software. But for two reasons it is a good things to use logging only sparsely: firstly logging is an expensive operation. Even if it is not that expensive, it's still extra work and consumes resources (IO is in general not that cheap because it is rather slow compared to everything else your plugin can do). Secondly if there are too many trees you don't see the forrest. This means that if you log too much the important stuff goes unseen. Thus report errors, and sparse special events that are good to now and happen rarely (like loading a plugin), log as much as you like during the development phase, but at a tournament make your application shut the f*** up. 
    1919 
    2020== Network Communication == 
    2121 You need someone to send data to: 
    22    If you send data over the network it has to be addressed to someone. For this the [doxygen:FawkesNetworkHub FawkesNetworkHub] provides two different methods: the first is unicast, sending the message to a specific receiver and the second is broadcast, sending the message to all currently connected clients. In general broadcasting should be used rarely, since in most cases not all clients want the information you send around. So in most cases you will want some kind of subscribe/unsubscribe scheme such that a client can turn on and off that you send him specific notification messages. 
     22   If you send data over the network it has to be addressed to someone. For this the [doxygen:FawkesNetworkHub FawkesNetworkHub] provides two different methods: the first is unicast, sending the message to a specific receiver and the second is broadcast, sending the message to all currently connected clients. In general broadcasting should be used rarely, since in most cases not all clients want the information you send. So in most cases you probably want some kind of subscribe/unsubscribe scheme such that a client can turn on and off that you send specific notification messages. 
    2323 Check the incoming component ID: 
    2424   If you receive messages for example using the [doxygen:FawkesNetworkClient FawkesNetworkClient] check the component ID for each and every incoming message. If you only look at the message ID it can happen that you receive a message with a message type you know, but for another component. This will lead to chaos and havoc because you interpret the message wrongly. Note that you shall check the component ID even if you only expect messages for one component. Output a warning or call aunt Tilda if you receive a message for an unexpected component ID. We call this defensive programming to eliminate problem because of other's failures before it bugs you. See the [source:trunk/src/tools/navigator_gui/navigator_gui.cpp navigator GUI] as an example.