Identifiers

Type identifiers consist of a lowercase "t" and meaningful, mixedcase notions. Variable identifiers are normally written in lowercase letters, their parts (if any) are separated by underscore ("_") characters. Constant identifiers often consist of a lowercase prefix formed by uppercase letters from the corresponding type identifier (if that's non-trivial), followed by a mixedcase, meaningful notion; a few constant identifiers are instead implemented using preprocessor defines, especially concerning "hard limits" for variables and some constants the values of which have to be accessible by the preprocessor for build-time error checking. Function identifiers are written like variable identifiers; additionally, their first part often refers to the source code file (or conceptual project part) they belong to.

Using Types

If a type is needed in several parts of the program, we define a new type identifier using "typedef". This way, we only have to change one place when we see that the original choice for that type wasn't "optimal".

Enumeration types are not defined with "typedef enum"; variables of such a type would waste much memory because they're "int"s. Instead, we define the constants using "enum" and define the type itself using "typedef unsigned char ...." or whatever might be appropriate. Additionally, we don't rely on the compiler assigning certain numbers to enumeration identifiers, instead we assign the numbers ourselves.

We don't rely on the "fact" that e.g. a char declaration is always interpreted as unsigned char by the compiler - some compilers interpret it as signed char. So we explicitly say signed char resp. unsigned char (unless we're actually using the char type for characters, and of course except for cases where e.g. a curses library header file simply says "short"...).

Marks

The source code contains lots of comments. Some of them are tagged with special "marks", so that their purpose becomes obvious at first glance and they can easily be recovered with "search" or "grep" commands. The following marks are used:

• NOTE: a comment which is important for understanding the source code
• IMPORTANT: a non-obvious fact which is important to know of for getting the program behavior right
• FIXME: a known bug or unintended program behavior; public releases shouldn't contain such marks, but there might be some "unimportant" bugs which shouldn't delay a release...
• CHECKME: code which should be revised or re-checked some time; this mostly concerns program design decisions which seem to be not satisfying or have some flaws.
• IMPLEMENTME: a feature idea which might be interesting and should be implemented some time
• IMPROVEME: code which is known to run slower than it could, but often the performance improvement will make the code much more complicated; since retawq is already pretty fast, such little performance problems aren't very interesting...
• REMOVEME: commented-out code which has been replaced by better code or isn't needed any longer for other reasons, e.g. old debugging messages; should be removed some time
• detach: we didn't forget to deallocate memory, we intentionally only detached a pointer.
• "should not happen": conditions which won't be true during normal program execution but might become true due to bugs; such code is only there in order to prevent the program from crashing (or other bad behavior) in case of bugs.
• "can't happen": conditions which are much less likely than the "should not happen" stuff; probably paranoid code
• #if 0: code which has been disabled because it isn't needed any longer or doesn't yet work as it should or requires changes somewhere else before it can work

Now if you still don't understand the source code, I give up... :-)