How to re-use, modify or fix codes in the sandbox

[Stephane Popinet]

Dear all,

While the "relative anarchy" reigning in the sandbox is generally a good
thing, I have noticed some common practices which could be improved, as
described in the set of "good practices" below, which you can also find
here:

http://basilisk.fr/Help#how-to-re-use-modify-or-fix-codes-in-the-sandbox

please read, follow and enjoy,

Stephane

----

As explained in the sandbox documentation anyone (with a login) can
access and modify any page in the sandbox.

The following list gives a set of “good practices” on how to re-use,
modify or fix codes in the sandbox. The overall guiding principles are
**communication** and **minimize code duplication**.

1. If you just want to reuse code published in another sandbox, **do not
copy it in your sandbox**, just include it using the appropriate path.
For example, to re-use the particles.h code in Antoon’s sandbox, you
just have to use

#include "Antoonvh/particles.h"

2. Do not hesitate to fix code directly in somebody else’s sandbox, in
particular, if you re-run an existing code and realize it is broken with
the current version of the solver. The original author will only be
grateful that you fixed their code!

If you are concerned that you should not modify code without the consent
of their original author, just contact them and/or put a note in the
documentation of the code indicating that you made a modification.

Also remember that, since everything is version-controlled, it is always
easy to go back to the original version, if necessary.

3. If modifications are required for the code you want to re-use, first
check whether these modifications can be made directly in the original
code (i.e. without breaking other uses of the code). If they are, just
make them there (**not in a copy in your sandbox**). If you are unsure,
check first with the original author.

Note also that it is often possible to add an option (for example by
adding a new default parameter to a function, a new compilation flag /
#define etc.) which adds the new functionality to the existing code
while keeping the default behaviour.

4. In the case where the changes are too extensive and *really* require
a different version, one should:

a. Copy the original code in one’s sandbox and record this change.

b. Only then modify this original code. Using darcs/history, this
makes it easy to see what has been modified between the two versions.

c. Document the change: Where does the original code come from? Who
is the original author? Why has it been modified? What changes have been
made?

d. Make a link to this new version (with explanations) **in the
documentation of the original code**, so that people using the original
version are aware that a new version exists (and why).