NetFXHarmonics Code Annotation Format

If you look at any of my open-source projects or even the Themelia source code, you will see that I use a special type of coding annotation.  The annotation format I designed (based on the designs of Sky Morey at Digital Evolution Group) is intended to maximize code readability and understandability.  The format is NOT a coding standard, but just what it says: an annotation format.

What’s that means?  Essentially when you are reading code you are constantly parsing all the symbols that you see.  Your brain can only work so fast, though, and some things have a higher parsing latency than others.  For example, VB code is incredibly verbose and uses long symbols to representing even the smallest things.  It will use the symbol “Then” where C# will use the symbol “}” (to some it may seem odd to think of a word as a symbol, but that’s all it is—you never read ever letter of a word you know.  If you know the word, your brain treats it as a symbol, not a series of symbols.)  It will also use two different character sets (what we call upper case and lower case) interchangeably, thus ever increasing the latency.  Though C# was designed with extremely low latency in mind, it, like all other languages, still has excess latency.

Thus, my code annotation format comes on the scene to make mental code parsing extremely fast.  It covers everything from how to case comments, when NOT to write comments, when to add metadata to class members, and how to deal with line breaks (the cardinal rule of the format!)  Most importantly, every annotation rule has an extensive commentary explaining why the rule exists and what value it provides in the long run.

Now, as with ALL THINGS EVERYWHERE, when you first start to apply it, it’s going to seem odd and it will slow you down at first.  After time, however, you will become extremely efficient at it and your code readability should dramatically improve.  When this is used in groups, it should seriously lower decrease the time it takes to read and understand the purpose of code.

You can view the NetFXHarmonics Code Annotation Format at http://www.netfxharmonics.com/document/code/format.