|
| 1 | + Date: 1999-08-04 |
| 2 | + |
| 3 | +To Think About When Contributing Source Code |
| 4 | + |
| 5 | + This document is intended to offer some guidelines that can be useful to |
| 6 | + keep in mind when you decide to write a contribution to the project. This |
| 7 | + concerns new features as well as corrections to existing flaws or bugs. |
| 8 | + |
| 9 | +Naming |
| 10 | + |
| 11 | + Try using a non-confusing naming scheme for your new functions and variable |
| 12 | + names. It doesn't necessarily have to mean that you should use the same as |
| 13 | + in other places of the code, just that the names should be logical, |
| 14 | + understandable and be named according to what they're used for. |
| 15 | + |
| 16 | +Indenting |
| 17 | + |
| 18 | + Please try using the same indenting levels and bracing method as all the |
| 19 | + other code already does. It makes the source code a lot easier to follow if |
| 20 | + all of it is written using the same style. I don't ask you to like it, I |
| 21 | + just ask you to follow the tradition! ;-) |
| 22 | + |
| 23 | +Commenting |
| 24 | + |
| 25 | + Comment your source code extensively. I don't see myself as a very good |
| 26 | + source commenter, but I try to become one. Commented code is quality code |
| 27 | + and enables future modifications much more. Uncommented code much more risk |
| 28 | + being completely replaced when someone wants to extend things, since other |
| 29 | + persons' source code can get quite hard to read. |
| 30 | + |
| 31 | +General Style |
| 32 | + |
| 33 | + Keep your functions small. If they're small you avoid a lot of mistakes and |
| 34 | + you don't accidentaly mix up variables. |
| 35 | + |
| 36 | +Non-clobbering All Over |
| 37 | + |
| 38 | + When you write new functionality or fix bugs, it is important that you |
| 39 | + don't fiddle all over the source files and functions. Remember that it is |
| 40 | + likely that other people have done changes in the same source files as you |
| 41 | + have and possibly even in the same functions. If you bring completely new |
| 42 | + functionality, try writing it in a new source file. If you fix bugs, try to |
| 43 | + fix one bug at a time and send them as separate patches. |
| 44 | + |
| 45 | +Separate Patches Doing Different Things |
| 46 | + |
| 47 | + It is annoying when you get a huge patch from someone that is said to fix 511 |
| 48 | + odd problems, but discussions and opinions don't agree with 510 of them - or |
| 49 | + 509 of them were already fixed in a different way. Then the patcher needs to |
| 50 | + extract the single interesting patch from somewhere within the huge pile of |
| 51 | + source, and that gives a lot of extra work. Preferably, all fixes that |
| 52 | + correct different problems should be in their own patch with an attached |
| 53 | + description exactly what they correct so that all patches can be selectively |
| 54 | + applied by the maintainer or other interested parties. |
| 55 | + |
| 56 | +Document |
| 57 | + |
| 58 | + Writing docs is dead boring and one of the big problems with many open |
| 59 | + source projects. Someone's gotta do it. It makes it a lot easier if you |
| 60 | + submit a small description of your fix or your new features with every |
| 61 | + contribution so that it can be swiftly added to the package documentation. |
| 62 | + |
| 63 | +Write Access to CVS Repository |
| 64 | + |
| 65 | + If you are a frequent contributor, or have another good reason, you can of |
| 66 | + course get write access to the CVS repository and then you'll be able to |
| 67 | + check-in all your changes straight into the CVS tree instead of sending all |
| 68 | + changes by mail as patches. Just ask if this is what you'd want. |
0 commit comments