From b5d0faaaffd1f319dd309406be104e92d2655206 Mon Sep 17 00:00:00 2001 From: David Walter Seikel Date: Sat, 2 Jan 2016 09:23:11 +1000 Subject: Added a wandering rant about standards. --- STANDARDS.txt | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 STANDARDS.txt (limited to 'STANDARDS.txt') diff --git a/STANDARDS.txt b/STANDARDS.txt new file mode 100644 index 0000000..da9ad2a --- /dev/null +++ b/STANDARDS.txt @@ -0,0 +1,128 @@ +In a non experimental project, this document would describe the coding +standards used. This is experimental code, we don't have any standards +yet. Not even any standard language. For the previous Java version of +matrix-RAD, I referenced a well known Java coding standard, and +documented the differences. There's still some value in that old +standard, we can just ignore the Java specific bits. + +In the end, we want to be language agnostic. By using sockets / pipes / +stdin/out / etc, and the Unix philosophy of little tools you hook +together that each do one job well. So we really don't care how badly +any given tool is written, so long as it works. Some of them will be +written be strangers across the Internet. This does need strong +communication standards though, which is what Nails is all about. + +We do want to be secure though. So eventually the non experimental +project this will grow into should have a core of well written code, +written to a standard. Lacking any standard for this experimental +version, this document will just have some random notes about style and +standards. + + +Coding standards +---------------- + +I want to use C and Lua, with assembler for speed critical parts. Speed +is an important issue, and these three are the best in their class for +speed. When used correctly, all three can also keep the code size down, +which is also important. Obviously security will be important for the +non experimental version, so keep that in mind. + +So far Lua as a prototyping language has been working well. So I can +see us roughing code out in Lua to start with, then rewriting it in C if +needed, then assembler if more speed is needed. + +On the other hand, we do want full functionality to be available to high +level scripting languages. While Lua is the chosen language, there's +been some success translating to and from Lua which may help us be more +agnostic here. There's others working on translating things to Lua, +based on the theory that since it's the fastest scripting lagnuage, that +might help speed up other scripting languages. + +In particular, translating LSL into Lua has so for been working well. +The parts that can be benchmarked soo far are very fast indeed, making +SL and OS look like the crippled snails that they are. Also, there's +some evidence that we might be able to translate Lua into ECMAScript to +run in web browsers, or run a Lua VM inside the ECMAScript VM. +Alledgedly, while the scripts run slower than LuaJIT can run them, they +are still quite fast compared to ECMAScript. We need this to support +legacy web browsers, which decided long ago to standardise on +ECMAScript. Alice loves her some JavaScript and node.js. + +We should allow early experimental work to be written in any language as +well. With the proviso that if it becomes a core part later, it should +get rewritten in a combination of Lua, C, and assembler. + + +Documentation standards +----------------------- + +This project started life as design documents on a MediaWiki based web +site, using MediaWiki markup. Those design documents where migrated to +the Drupal system that replaced the site. At this point every one +wanted to use a different markup syntax. lol + +I solved this by installing a few markup systems, but the majority of it +got written as what Drupal refers to as "simple formatting", which +basically allows the use of certain HTML tags, plus a few nicities. + +Eventually code started to get written by me, I put it on GitHub. At +around the same time, I was busy transferring the Team Purple website +from individual web applications to SourceForge. Team Purple are the +developers of the Imprudence and Kokua viewers. Later SourceForge +turned evil, so I started looking for other project hosting options. +GitHub has a wiki part, but they squeeze you into a tiny column in the +middle of the web page, and you can't do colours. BitBucket (the other +major project hosting site used by Team Purple) seems to want to sell +you JIRA, so might also not be suitable. In either case, they both +might turn evil as well. Can't find a decent project hoster, sigh. + +It looks like it helps to be generic, instead of constantly converting +between each of these markup formats each time we change hosting system. +All of these markup systems get parsed by active code somewhere at +viewing time, to get translated into HTML+CSS+JavaScript that is sent to +your browser. All of the documents are static. Sure, matrix-RAD +included a worlds first active manual, you could test out matrix-RAD +commands right there in the docs, but we are going a different way this +time. We are no longer living in the web browser, but replacing it with +a virtual world, that might happen to include web pages on prims, but +that's not our main thrust for UI stuff. + +Sooooo, to avoid a lot of work, how about we just make the documentation +static HTML web pages, and be done with it? Markup systems are just a +way to make HTML more palatable to ordinary users, but ordinary users +are not writing the design documentiation and such. They all get +translated to HTML, so let's just write raw HTML ourselves. Keep it +simple, no fancy CSS or Javascript shit. So we avoid markup, we avoid +having to translate from markup to markup, and we avoid the rendering +step of translating markup to HTML. We avoid having to parse the +documentation at all, just send it to any old web browser. + +In this way, we can just throw the basic documentation up on any old web +server. Enough for people to learn about it, get interested, and get it +up and running. People editing this stuff could just use any HTML +editor if they like, including translating their favourite markup to HTML. + +Currently there's ordinary text files as well. A few of those should +stay as ordinary text, but some (or most) could get converted to HTML, +then linked in to the rest. Also, I should link up the existing pages +now, some more internal navigation. + + +On the other hand, once they have the system running, there's - + +Internal documentation standards +-------------------------------- + +matrix-RAD included plans for being able to edit down to the code level +from within the web browser running matrix-RAD apps. SL and OS include +world building tools you use from inside the world, including editing of +scripts. So SledjHamr is no different, it will include tools you can +use from inside the world, to edit everything about the world. Which +should include stuff like the matrix-RAD JavaDocs extensions to help +self document code and other fancy things. Obviously this will include +coding standards, and tools to help with those standards. + +Once things start being less experimental, then we can decide how that +all works, and the coding standards to suit. + -- cgit v1.1