Software Development Guidelines

A price we must pay for building (anything) is that we must do it well enough. For programming, that implies adherence to some minimal standards, and awareness of how to improve.

We'll gather programming principles here that will become our minimum expectation, as well as discuss general principles. Part of programming is documenting the result in a form useful to others. To that end we have a template for internal software documentation.

One simple principle that has arisen in multiple conversations is that of providing a characterization for every "thing" in a program. We resist the temptation to refer to "objects", as that can have a very specific meaning in certain contexts. Some obvious "thing"s are functions, data structures, or blocks of related code. This is mostly about commenting style. A structured commenting approach can make it easier for others to find/skip/understand parts of the code.

Another very general principle is to make things changeable. Aside from facilitating testing, and hence increasing reliability, it has the implication that the result will be understandable to others.

A description of programming style principles was created by MFCF many years ago. While it does contain some techno-political commentary, and many examples specific to one old language (C), the general principles described are still useful. It may be found as the "man page" mfcf-programming-style on MFCF systems. These programming style guidelines have been converted to a WWW page, and now contain some language-independent observations and guidelines.

In addition to principles for creating new code, we should make sure we address the issue of determining whether to continue to update existing code or create new code to deal with a similar issue.

The OFIS project, with which CSCF is involved, has both programming and database coding style conventions.