quality.txt, (C) Yann GUIDON Dec 30 2000 Quality policies and some helpful advices I must recognize that i'm not the best coder of the world. My memory is limited and I sometimes face difficult compromises that affect the code i write, whatever the langage. We all know that a good documentation and easy to use SW are sometimes more important than the speed or usefulness improvements. For example, you just discovered this text and you decided to read it. You have opened it in a text editor of your choice, assuming (from the .TXT file extension) that it is in ASCII format. You now enjoy its insightful contents and it all lasted only a few seconds :-) The same goes for source code. The goal of this document is not to "rule" but to "guide" coders, whatever their project. When a package must be released, it is often very long to check the consistency and status of every file. Even though it's not considered as a "noble" task, each one should consider spending a large amount of time writing comments and READMEs. It is not possible either to spend all you time writing documents, but please consider the total amount of time that will be spent by people trying to understand your code. If you code all the time, you don't document, and if you write comments all the time, there is no code written in the end. That is why the comments in the sources must be written while programming. It doesn't take much time at all because it is an integral part of the coding activity and it follows closely your ideas of the moment. For one ASCII character of code, there should be in average one character that describes what is being done. This average concerns the whole file. This kind of documentation is very helpful, not only for the newcomer, but for the coder himself, because it helps him debug the code. When the code is ready and ready for distribution, an external file (ie HTML) can be written, describing the overal architecture of the code and the basic principles. I consider a program source file as a story that should be understood with the first reading. A source code must tell you a story : good comments with a good style (not "only" a descriptive comment) can explain what is really going on. Old good spaghetti style is not good. Not because it is spaghetti, not because it makes use of direct jumps or labels (we always need some from time to time) but because the structure doesn't appear during a linear reading. Of course, the "story" of the source code can appear to experienced programer, or the one who coded the file. It doesn't mean that everybody can understand it, esecially newbies... -o-O0O-o- Now, here are some practical, everyday advices : - When creating or updating a file, always put the copyright, the author's (you) name, and the date. I usually type "date" on a Un*x console and then cutn'paste it in emacs. - Indicate as much hints as possible, even though it ends up with pages of comments. They'll be sorted later if they're useful. Removing comments might lead to some misunderstanding with others. - Here are some standard hints, after the date and name : * type of modification : several lines are often necessary (unless you only corrected a mistyped character...) * name of the file. It might be lost when sent in an email or when printed, depending on the software (do not think that because your SW does it for you, the others will have it too). * compilation command, or indication of the makefile. This shows what flags and compiler are needed. * if it is included by/in another source, name the parent file. * Portability across platforms : indicate what tool is used (ie a certain flavour of) or if there are incompatible features (ie: a particular data alignment/ordering/organisation, CPU-dependent structures...) * Link to documentation : in the directory or in the package, or on the web, etc... * whether is is tested, how and in what circumstances (platforms, dataset, coverage...) * Status of the file : something like the following notes -> just created, -> not yet working -> just working -> enhancements -> satisfying -> a bug was discovered somewhere... -> foolproofed -> don't touch -> locally released -> ready for public release The hints apply for a single file, a directory, a package... Note that these hints are highly subjective and are influenced by everyone's standards. This evaluation can be summarized in a single number, from 0 to 10. * 0 corresponds to a rather inexistent or empty package * 1 : the first functions are written * 2 : some stuffs are starting to work together * 3 : addition of some test vectors and testbenches * 4 : under debug * 5 : enhanced * 6 : all features are available * 7 : correctly working * 8 : fully documented * 9 : exhaustively tested across many platforms * 10 means that it can't be enhanced anymore. Of course this is only indicative about the general status. The mark can vary a lot during the life of the project. The goal of thes hints and subjective evaluations is to help maintain and bundle the packages. A directory containing low-evaluated files will not be included in a package. Ideally, a package should only contain "10" files but in practice and in a closed-room development environment, some factors are not revelant. A F-CPU package would average 8 for practical reasons (time, platforms, prototyping/evaluation only etc). Today (dec. 2000), all the files of the F-CPU project don't comply with this policy. Before the distribution grows out of control, it becomes necessary to closely examine, document and test all the source code. Then, only "satisfying" files or directories would be included in a certain package (as several F-CPU packages are possible). ----------------- I hope that this text has helped you understand the importance of individual quality evaluation. Next time you finish a software, don't think that it is ok : higher quality means less time spent during debug sessions and packaging. It also means more attention on the code writing : correctly indenting a source file is not enough. Please spend more time explaining what you do (on the file). Remember that few good working code files are better than a whole bunch of unorganized, unsorted, undocumented files that don't work. The first has more value because it can be easily compiled, executed, modified and redistributed. There can be many F-CPU packages or file bundles but this guidelines will influence whether a file or directory can be included in my own tree. The verification can't be automated and therefore, a little help from everybody can speed up the work. Have fun, YG