FIXME conditional compilation is a last resort
-FIXME s_char
-
Robustness
----------
FIXME what to do on error
+Sanity checking
+
+In many places, the code checks for conditions that should not happen,
+and then tries to recover. This is sound defensive programming.
+Please use CANT_HAPPEN() and CANT_REACH() for this purpose, because
+they log the error condition, and optionally abort the program, or
+write out a core dump. This is called an "oops".
+
Buffer overruns
FIXME
* You can get a copy with getFOO() and write it back with putFOO().
- Yielding the processor invalidates the copy. In particular, if you
- yield the processor between get and put, and another thread changes
- the game data, then put will clobber that change, possibly resulting
- in a corrupted game.
+ Putting updates both the object in memory and the disk file.
- Therefore, you have to re-get after a yield, and repeat any checks
- you already made. If you can afford to bail out when something
- changed at all, use check_FOO_ok().
+ Any change to the object invalidates the copy. Putting such an
+ invalid copy will clobber the change(s) that invalidated it,
+ possibly resulting in corrupted game state. The code oopses on such
+ puts, but it can't repair the damage.
- Putting updates both the object in memory and the disk file.
+ There are two common ways to invalidate a copy: calling a function
+ that updates the object you copied (unless it does that through your
+ copy), and yielding the processor, which lets other threads update
+ the object you copied.
+
+ Therefore, you have to reget after a possible invalidation, and deal
+ with changes. In particular, if you checked whether the object is
+ suitable for a task, you need to check again after regetting it. If
+ you can afford to bail out when something changed, use
+ check_FOO_ok().
+
+ Function comments should state what objects the function can update.
+ Unfortunately, they generally don't.
- If you write a function that takes a pointer to an object, think
- twice before you put it, and if you do, mention it in the function
- comment.
+ It's best to keep puts close to gets, both in runtime and in the
+ source code.
* Bmaps have special access functions.
you yield. If you only updated the working bmap, then you can call
writebmap() instead.
+Reading player input
-CVS
+Reading player input can fail, and you must check for that.
+Neglecting it can break the interrupt feature for players (normally
+Ctrl-C), and produce extra prompts that could confuse clients. Even
+worse is neglecting it in a loop that terminates only when input is
+read successfully.
+
+When reading input fails, you should normally abort the command with
+status RET_SYN. There are exceptions, e.g. when aborting a pinpoint
+bombing run over the target.
+
+Some functions to read player input return a special error value you
+can check, e.g. recvclient(), prmptrd() and uprmptrd() return a
+negative value, getstring() and getstarg() return NULL.
+
+Others return the same error value for failed read and for successful
+read of input that is invalid. Then you need to check
+player->aborted; if it is set after a read, the read failed.
+
+
+git
---
Commit related changes together, unrelated changes separately.
-See chapter Change Logs in the GNU coding standards for guidelines on
-log messages. Try http://www.gnu.org/prep/standards_40.html#SEC40 or
-search the web for `gnu coding standards change logs'.
+Write meaningfull commit messages. Start with a single short line
+(ideally less than 50 characters) summarizing the change, followed by
+a blank line and then a more thorough description.
+
+The purpose of the change log is not to explain how the code works;
+that should be done in the source code itself. It's to explain *why*
+you made the change, and what is affected by it.
Don't change whitespace gratuitiously, say just because your editor
screws up tabs. Such changes make it much harder to figure out who
Sasha Mikheev on indentation:
-The empire indentation style can be achived by using
+The empire indentation style can be achived by using
indent -orig -i8 foo.c
or in old c-mode emacs (versions before 19.29):
projects / empserver / blobdiff