Doesn't work

Q: Gurus! Help me! Xyz doesn't work correctly. What's wrong?

A: Did you update all projects and recompile them? ...<hups>

Screen is empty?

Q: I don't see anything. Just plain black with GL.

A: Probably you have some problems with your X drivers etc. Update your /usr/X11R6/include/GL/*.

A2: unset LANG

Compiling

Q: How to compile?

A: With luck.

Debug

Q: How to set debug options?

A: Java: make run DBG="-d gzz.client.foo"

C++/GL: make rungl DBG="-G JNI.general -G JNI.foo"

Remember: if you see something like dbg_paperquad in the source it was 
          probably initialized with 
DBGVAR(dbg_paperquad, "Renderable.paperquad");
So, use DBG="-G Renderable.paperquad"

To find these, use grep: that's the most important tool of a programmer. Tjl has the aliases:

alias gj='find . -name "*.java" | xargs grep '
alias gc='find . -name "*.[ch]*" | xargs grep '
alias gp='find . -name "*.[p]*" | xargs grep '

for this. E.g.

gc dbg_paperquad

will find you the above line.

It's more efficient to use boolean primitive to check debug strings. So, you are NOT allowed to construct debug messages like:

class Foo {
    static public boolean dbg = false;
    private void p(String s) { if (dbg) pa(s); }
    private void pa(String s) { System.out.println("Foo::"+s);


    public void example(int i) {
        p("Just a test " + i)
    }
}

If you use this, debug string is always created using immutable string concatenation and that isn't very efficient in java. Well, instead of previous example, write a bit longer but more efficient:

class Foo {
    static public boolean dbg = false;
    private void pa(String s) { System.out.println("Foo::"+s);


    public void example(int i) {
        if (dbg) pa("Just a test " + i)
    }
}

Creating well documentated source

1. Documenting is part of good source

   • In Fenfire we use java-doc and docxx

2. See the documentation already exists.

   • The most important part of documentation is the first line.

3. Write the documentation

   • Remember the importance of first line in class and method documentation.

   • Write the truth, don't lie.

   • If method implements an interface it's javadocced by the interface. So, don't make any worse documentation in implementation, leave it alone or mark it with comment // javadoc in interface etc.

   • Some helpful questions which you can answer in the doc:

     • How does other classes use this?

       • Who calls it?
       • What for?
       • When?

     • How many instances are there of this class?

     • What is it used to represent?

     • What different implementations can there be?

     • Would a good example hurt?

4. Test

   • Ask your friend to look the compiled document and ask what the class do. If the answer is mess, your documentation is even worse mess.