matrix-RAD - coding standards

The people Coding standards Design Rewrite rule TODO DONE Sun Java

Javadocs Class Hierarchy Index NAWS MTRX security servlets Skang Squeal & Stuff zen developer

coding standards

I will not bother to run a spelling checker over the source, it takes too long to ignore the actual source code bits. So you will have to put up with spelling errors in the documentation. Spelling errors in the source code bits should get caught during debugging B-).

Matrix-RAD is written in fully portable Java, with Java Native Interface (JNI) stuff written in C for anything that requires it. Unlike Java itself, we will not just stick to the lowest common denominator, but will use the unique features of each OS as appropriate with JNI code. The Ambysoft Inc. coding standards for Java V17.01c will be used (referred to as "Ambysoft" from now on), every coder must read that. As many OS's as possible will be catered for, which means that Java 1.1.5 has to be used. On the other hand, more recent versions of javadoc provide better looking docs, and can be convinced to do the correct thing with Ambysoft tags. JDK 1.4.0 is currently being used to develop with, but JDK 1.1.8 classes.zip is used to compile the source itself.

Support for Java versions less than 1.2 will be dropped after 2008.

To see the coding standards document, either the developer archive will have to be installed, or you can get it from Ambysoft. It's not updated very frequently, I've been using V17.01c for years, the latest version is V17.01d, which we will change to Real Soon Now.

The Ambysoft standard says to document the differences from the standard, while any individual difference should be documented where it occurs, there are some overall differences and comments that will get documented here.

Priorities :

Ambysoft says that I should rank the following factors, without clearly defining what these factors mean.

Simplicity can mean simplicity of code or simplicity of use, which are often mutually exclusive. Maintainability includes simplicity of code, so I think that simplicity in this context means simplicity of use for the user.

Robustness and safety could be the same thing, but I guess safety refers to security issues, and robustness refers to crashing issues.

Reusability can mean letting others use the class in a black-box manner. On the other hand, it could mean internal reusability of this class and it's methods.

Size should mean total resources consumed, including things like size of the executable, amount of ram and HD needed while running, and amount of storage required for data while not running. These can sometimes be in conflict. Size of the source is not important, it must be big enough to fulfill all the other requirements, and then there's the over documentation that Ambysoft insists on B-).

Would debugability fall under testability or maintainability? All three have major areas of overlap. They also have a big impact on robustness and safety. The default and overall rankings are -

Portability - This will need to run on any OS with a 1.1.5 JVM, or higher.
Simplicity - All software should be as simple to use as possible for the target audience.
Robustness - Must never crash, and must warn the user if the various connections time out.
Safety - Privacy and cracking issues need to be taken into consideration.
Testability - This is a client / server type setup. Should be able to get them to run on the same computer to test.
Maintainability - This is open source, others will need to read this.
Reusability - This is supposed to be as generic as possible.
Speed - There is no need for speed, only a need to keep CPU usage to a minimum while it is just ticking over. For the GUI, responsiveness is a major issue. End to end and back speed is important.
Size - All else being equal, smaller is better.

Any class that requires different rankings will have a similar table in its javadoc, with reasons.

Since we now use recent versions of javadoc that understand the -tag option, we need to modify the usage of Ambysoft tags to suit. We use -tag rather than write taglets, cause this is all one line stuff. Mostly Ambysoft has extra stuff in the tags that just looks silly in the resulting javadocs. Sun now recomends the use of a dot in the name of custom tags, to avoid namespace collisions with their own tags, so I use a dot before the tag name (@.modifies).

@.requires - Added this to specify the minimum version of Java required.
@.reference - @see now does what we want, so no need for another version.
@.modifies yes - The "yes" bit has been dropped, as it looks silly in the result.
@.modifies no - Dropped completly, if there is no "@.modifies x" tag, nothing gets modified.
declarations - No need to include the name in the javadoc comment, it is named nearby anyway, and the resulting javadocs look silly otherwise.

See version numbers for a description of the version number system that has to be used for matrix-RAD.

The standard says not to use the wildcard version of the import statement, but for java.lang.* I use (or will use) most parts anyway. Although java.lang.* is usually imported by default, we specify it anyway, even though some compilers complain. It's good to not assume anything. Since these are all Skang modules, or parts of Skang, I import net.matrix_rad.skang.* most of the time.

Anything that is not indented, that is it is flush to the left margin, is temporary or debugging code. I tend to leave debugging code in and just comment it out, cause if I needed this before to debug things, I'll probably need it again to debug something else. While C++ style comments are used for real coments, both C and C++ style comments are used for commenting out stuff, C++ style particularly if I just want to comment a single line, or do it line by line.

Not documenting something in the source because javadoc will inherit the documentation from the super class is probably against Ambysoft. I don't duplicate documentation for a few reasons, it makes things hard to maintain, it bloats out my footprint, and javadoc takes care of the problem anyway B-). Java 1.4.0 only inherits method javadocs, not field javadocs, even @inheritDoc only works for methods. I'll proceed as if it DID work, cause some of my field javadocs are huge. When Sun fix their software, I'll be ready B-). See above for why I refuse to duplicate documentation.

coding standards

This file was last modified on Monday, 22-Nov-2004 11:33:20 EST