This document is a modification of the original proposed coding standards presented in 1994 by Jim Hall, and later updated with additional suggestions by Hannibal Toal in 1995, and updated again by Jim Hall in early 1998.
This latest draft is really just a compilation of other people's coding standards. I have properly cited the references.
These coding standards were written to allow you as much coding freedom as possible, while keeping the code in a state that is readable and understandable by others. Please read carefully the sections that apply to your project.
Reference: What is copyleft?.
The simplest way to make a program free is to put it in the public domain, uncopyrighted. This allows people to share the program and their improvements, if they are so minded. But it also allows uncooperative people to convert the program into proprietary software. They can make changes, many or few, and distribute the result as a proprietary product. People who receive the program in that modified form do not have the freedom that the original author gave them; the middleman has stripped it away.
In the FreeDOS project, our aim is to give all users the freedom to redistribute and change FreeDOS software. If middlemen could strip off the freedom, we might have many users, but those users would not have freedom. So instead of putting FreeDOS software in the public domain, we "copyleft" it. Copyleft says that anyone who redistributes the software, with or without changes, must pass along the freedom to further copy and change it. Copyleft guarantees that every user has freedom.
Copyleft also provides an incentive for other programmers to add to free software. Important free programs such as the GNU C++ compiler exist only because of this.
Copyleft also helps programmers who want to contribute improvements to free software get permission to do that. These programmers often work for companies or universities that would do almost anything to get more money. A programmer may want to contribute her changes to the community, but her employer may want to turn the changes into a proprietary software product.
When we explain to the employer that it is illegal to distribute the improved version except as free software, the employer usually decides to release it as free software rather than throw it away.
To copyleft a program, first we copyright it; then we add distribution terms, which are a legal instrument that gives everyone the rights to use, modify, and redistribute the program's code or any program derived from it but only if the distribution terms are unchanged. Thus, the code and the freedoms become legally inseparable.
Proprietary software developers use copyright to take away the users' freedom; we use copyright to guarantee their freedom. That's why we reverse the name, changing "copyright" into "copyleft."
Copyleft is a general concept; there are many ways to fill in the details. In the FreeDOS Project, we suggest that you use the GNU General Public License (GNU GPL). However, the ultimate choice of what copyright/copyleft to use is up to you.
Reference: GNU General Public License
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. In the FreeDOS Project, we suggest that you use the GNU General Public License (GNU GPL). However, the ultimate choice of what copyright/copyleft to use is up to you.
To apply the GNU GPL to your program, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the copyright line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does.
Copyright (C) 20yy name of authorThis program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 20yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than show w and show c; they could even be mouse-clicks or menu items--whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a copyright disclaimer for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker.
signature of Ty Coon, 1 April 2000
Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.
You should avoid using the term freeware when referring to your programs. This term has no clear meaning today, and can mean anything from "the program is free, but you can't have the source" to something like "in the public domain." Similarly, avoid the term free software when its meaning may be unclear.
Instead, state directly what the copying and redistribution restrictions are, if any. If you are releasing your program into the public domain, say so. You should state your redistribution license in a file named either COPYING or LICENSE, which will make it easier for someone to find your copying policy.
If you wish your program to be distributed under the GNU General Public License, apply the proper text to your source files, include the GNU GPL as the file COPYING, and explicitly state in your documentation that your program is distributed under the GNU GPL.
The worst situation you can get yourself into is to not clearly state how your program may be used, and then have someone come along and claim your code as their own.
If someone else sends you a piece of code, and you use it in your program, you must fully document where you got it. Include the other person's name and email address, and any other appropriate contact information.
If you found someone else's code, and you wish to include it in your program, then things get a little tricky. It would be far easier if everyone wrote software using a license like the GNU GPL, but they don't. Therefore, you need to be careful about what you include in your source code.
Make sure the other person's code allows you to incorporate it into your own program. If the other program is in the public domain, then it is probably okay. If it is freeware, it may be or it may not.
You should make all efforts to contact the original author before you include any foreign code into your program. Have the original author send you a document, if possible, explicitly giving you permission to use his code in your program.
When you incorporate the other person's code, always give full credit. Never claim someone else's work as your own. This is not only unethical, but you will likely wind up in some kind of legal trouble later on down the road. And the rest of us will point to you and laugh softly. So don't use anyone else's code without giving full credit.
The following is usually acceptable when referring to someone else's code:
/* this bit submitted to my by John Doe, jdoe@foo.net */
Or this:
/* This code was lifted from BAZ, by John Doe (jdoe@foo.net). * However, I have not been able to reach John Doe at this address, but * the BAZ program was released under the GNU GPL ... */
We prefer that all FreeDOS programs be written in either C or Assembly. Certainly all Base FreeDOS programs (those programs that reproduce the functionality of MS-DOS) should be written in either C or Assembly, as indicated by the FreeDOS Spec.
All libraries that you use to create your program should also be open source projects. Please check the redistribution restrictions for your program. If the libraries are not open source, then others may have trouble obtaining the libraries and, hence, in building your software.
You should make all efforts to use an existing library before writing one of your own. For example, the GNU getopt library has already been written by the Free Software Foundation to help you parse a command line in C programs. Other libraries also exist for language internationalization and console i/o.
If we all use the same libraries, then the overall maintenance of our FreeDOS programs will be much easier. By updating one library, we can extend the functionality of all FreeDOS programs that link with it.
Reference: GNU General Public License, FreeDOS Spec
All programs should use the same format when printing their usage statements. This presents a more consistent interface to the user, and lets people find information in the same place in every program.
The /? command line option should always display a usage statement, and then the program should immediately exit. Programs should use this format to display their usage:
name - one-line description of what the program does
usage synopsis
OPTIONS:
some options
For example, the following might be the usage for the CHKDSK program:
chkdsk - Check the disk for errors.
chkdsk [d:] [options]
Options:
/f
Fix errors on the disk when found.
/v
Display the name of every file as the disk is checked.
If no drive is specified, check the current disk for errors.
If your program has more than one possible synopsis of usage, then you should display them both. For example, the JOIN program:
join - Join a drive to a directory.
join d: d:path
join d: /D
Options:
d:
The drive letter you want to set up.
d:path
The full path which will be assigned to the drive.
/D
Delete this join definition.
If you wish to display your copying policy in your usage statement, please be brief as a long copying policy can take up valuable screen real estate. One or two lines would seem appropriate. The following might be one way to announce that your program is distributed under the GNU General Public License:
Gnomovision - which makes passes at compilers Gnomovision version 69, Copyright (C) 20yy James Hacker This program is free software (GNU General Public License) Usage: GMV [/?]
For other copying policies that you wish to announce in your usage statement, please use a similar syntax.
We prefer that you write all FreeDOS programs using the ANSI standard for your compiler, so that your code is instantly portable to any compiler. However, we recognize that is is often impossible. Therefore, any compiler-specific functionality that is used in your program should be well documented. This will aid someone else when they try to build your program using a different compiler.
The following is one example in how to document a compiler-specific function:
/* reboots the computer in a compiler-specific way */
/* uses Microsquish C to reboot the computer */
/* usage is reboot(WARM_BOOT) or reboot(COLD_BOOT) */
if (user_wants_to_reboot)
{
reboot(WARM_BOOT);
}
Ideally, all compiler-specific functionality should be encapsulated
using #ifdef statements, using proper conditionals that allow
the program to build using a variety of compilers. For example, the
following is one way to use these statements to support different
compilers:
/* wait one hour: */ #ifdef _foo_c /* c compiler by Foo corp */ hr_wait (1); #else sleep (3600); #endif
You should use similar methods for other programming languages.
C code should be indented using the GNU indent program, using the -gnu option. Let the program do the work for you.
We do not have any indentation standards for ASM code. Please use good judgement, and use indentation that others can easily read.
All programs should be well documented using external documentation files. The following are the minimum that we request for any source distribution:
This file contains a description of the program, and should also contain a description of the copyright and redistribution restrictions, if any.
This file should explain, in detail, the compiler used to build the program, and the exact steps that are required to build your program. If your program requires that other libraries be downloaded and compiled first, document this here.
The Help file should be in the style of the UNIX man program, which is as follows:
NAME
One line to describe your programSYNOPSIS
Sample usage for your program, showing all the possible permutations of command line optionsDESCRIPTION
An in-depth discussion of your program, which should also describe how the program may differ from MS-DOSOPTIONS
A list of all options and their meaningEXAMPLES
Sample command lines, if appropriateBUGS
A list of obvious bugsAUTHOR/CONTRIBUTORS
A list of contributors to the program, or AUTHOR if there is only one contributorCOPYING
How the program may be copied or redistributed.
This file contains a description of the changes over the program's revision history. You should document what features were added/removed in each release, and what the release version was. Also include the date the software was made available for download, and any other information that seems appropriate.
This file contains a copy of your copying license. Put nothing else in the license file. If your program is in the public domain, then say so in this file. If you use the GNU GPL, then copy the GNU General Public License to this file.
Please use the zip file format when distributing your code. Zip files, as defined by the PKZIP program, are the defacto archive file format. The Info-Zip project has released DOS versions of a PKZIP compatible archiver and de-archiver.
Please refer to the FreeDOS Spec for a list of program behavior, including command line usage.
Unless otherwise stated, FD-DOC HOWTO documents are copyrighted by their respective authors. FD-DOC HOWTO documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies. Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions.
All translations, derivative works, or aggregate works incorporating any FD-DOC HOWTO documents must be covered under this copyright notice. That is, you may not produce a derivative work from a HOWTO and impose additional restrictions on its distribution. Exceptions to these rules may be granted under certain conditions; please contact the FD-DOC HOWTO coordinator at the address given below.
In short, we wish to promote dissemination of this information through as many channels as possible. However, we do wish to retain copyright on the HOWTO documents, and would like to be notified of any plans to redistribute the HOWTOs.
If you have any questions, please contact the FD-DOC coordinator at jhall1@isd.net.