Coding for Open Source

This is a note that is intended to be the start of a discussion. I am not laying down the law, just trying to get some ideas going. All in my opinion.

If we are to write code for Open Source projects and put it under change control, we must take responsibility for it. Think about it. Own it.

One thing this means is to have a reasonable header as an introduction at the beginning of any files/modules. This should contain:

• Name of module. Title. If the name is an abbreviation, expand it.
• Name of author(s) and the organization name (if any). Contact information, if applicable: We're proud of our stuff. If someone else want to use it they should know who to contact, if they want to discuss it. We might learn something to our advantage.
• Time stamp & date: Of original creation or significant change. This can be useful in the event that the module gets disconnected from the source control system. Oh, it happens. (We don't need to reproduce what the source control system does though, that stuff about author, change made, version, date, reason for change etc. belongs to Subversion. Use the Source.)
• Explanation of function: A decent plain-language explanation in high-level terms of what the module does. This is so simple to do when you create the module, please consider the rest of us and, probably, your future self!
• Any disclaimers, or mealy-mouthed wording desired: to disclaim responsibility to the public and to ask for credit if someone reuses or re-purposes the module. Whatever our organization decides.
• Credits to other projects from whom we have stolen er...borrowed code or ideas. Here or in the code. Within reason; I doubt if we need to know that your mom is awesome (although she is, indubitably! She and I are best pals.)
• Any tie-in to versions of hardware - although we hope we have software and hardware co-located for version control, especially if we are maintaining multiple versions. (Cthulhu help us, if we are.)

In the body of the code, every function and obvious group of lines of code, should have a comment explaining what it does. Don't bother to document the parameters of a function; just pick parameter names and types that are helpful to the reader.

When re-using someone else's code, be a mensch and carry forward the credit, even if it is just in a comment.


Variable names, function names, you know the drill. Helpful ones are helpful and future coders will love you for your coolth. Explaining them with a comment is even better.

Format and structure the code according to your desires, unless you are editing an existing module. In that case, follow the example set by the original author. That includes names of things too. If the code is a combination of different formatting styles, you'll get treasure in heaven for making it consistent throughout. Only another coder will care. If the existing format/structure/naming convention makes you puke and you don't have time to modify everything, do what you will. The Hounds of Hell are coming on the next bus.

Naming of loop index variables. Go wild. The tradition of using i, j, k, as integer index variable names is long and honorable and goes back to FORTRAN - remember you are the privileged initiate of an ancient and noble craft.

Just because we hack, it doesn't have to look like garbage. Good code can be a lovely thing to be appreciated in an easy chair with a glass of wine. Consistency. Style. It speaketh volumes...

And lastly, if you are picking up a module, try to understand what the fuck the thing does. It is only code. Consult your team. Do the rubber duck walkthrough either with a duck or a person. If that stupid machine can understand it, you can as well. It's only got a teeny, tiny, brain...while you are a Lord of Creation!