diff options
author | David Walter Seikel | 2016-01-02 09:23:11 +1000 |
---|---|---|
committer | David Walter Seikel | 2016-01-02 09:23:11 +1000 |
commit | b5d0faaaffd1f319dd309406be104e92d2655206 (patch) | |
tree | 47b18c0547fee870d7a8e6e5cce68634b03c7a24 | |
parent | Point to local copy of design docs, instead of online copy. (diff) | |
download | SledjHamr-b5d0faaaffd1f319dd309406be104e92d2655206.zip SledjHamr-b5d0faaaffd1f319dd309406be104e92d2655206.tar.gz SledjHamr-b5d0faaaffd1f319dd309406be104e92d2655206.tar.bz2 SledjHamr-b5d0faaaffd1f319dd309406be104e92d2655206.tar.xz |
Added a wandering rant about standards.
Diffstat (limited to '')
-rw-r--r-- | STANDARDS.txt | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/STANDARDS.txt b/STANDARDS.txt new file mode 100644 index 0000000..da9ad2a --- /dev/null +++ b/STANDARDS.txt | |||
@@ -0,0 +1,128 @@ | |||
1 | In a non experimental project, this document would describe the coding | ||
2 | standards used. This is experimental code, we don't have any standards | ||
3 | yet. Not even any standard language. For the previous Java version of | ||
4 | matrix-RAD, I referenced a well known Java coding standard, and | ||
5 | documented the differences. There's still some value in that old | ||
6 | standard, we can just ignore the Java specific bits. | ||
7 | |||
8 | In the end, we want to be language agnostic. By using sockets / pipes / | ||
9 | stdin/out / etc, and the Unix philosophy of little tools you hook | ||
10 | together that each do one job well. So we really don't care how badly | ||
11 | any given tool is written, so long as it works. Some of them will be | ||
12 | written be strangers across the Internet. This does need strong | ||
13 | communication standards though, which is what Nails is all about. | ||
14 | |||
15 | We do want to be secure though. So eventually the non experimental | ||
16 | project this will grow into should have a core of well written code, | ||
17 | written to a standard. Lacking any standard for this experimental | ||
18 | version, this document will just have some random notes about style and | ||
19 | standards. | ||
20 | |||
21 | |||
22 | Coding standards | ||
23 | ---------------- | ||
24 | |||
25 | I want to use C and Lua, with assembler for speed critical parts. Speed | ||
26 | is an important issue, and these three are the best in their class for | ||
27 | speed. When used correctly, all three can also keep the code size down, | ||
28 | which is also important. Obviously security will be important for the | ||
29 | non experimental version, so keep that in mind. | ||
30 | |||
31 | So far Lua as a prototyping language has been working well. So I can | ||
32 | see us roughing code out in Lua to start with, then rewriting it in C if | ||
33 | needed, then assembler if more speed is needed. | ||
34 | |||
35 | On the other hand, we do want full functionality to be available to high | ||
36 | level scripting languages. While Lua is the chosen language, there's | ||
37 | been some success translating to and from Lua which may help us be more | ||
38 | agnostic here. There's others working on translating things to Lua, | ||
39 | based on the theory that since it's the fastest scripting lagnuage, that | ||
40 | might help speed up other scripting languages. | ||
41 | |||
42 | In particular, translating LSL into Lua has so for been working well. | ||
43 | The parts that can be benchmarked soo far are very fast indeed, making | ||
44 | SL and OS look like the crippled snails that they are. Also, there's | ||
45 | some evidence that we might be able to translate Lua into ECMAScript to | ||
46 | run in web browsers, or run a Lua VM inside the ECMAScript VM. | ||
47 | Alledgedly, while the scripts run slower than LuaJIT can run them, they | ||
48 | are still quite fast compared to ECMAScript. We need this to support | ||
49 | legacy web browsers, which decided long ago to standardise on | ||
50 | ECMAScript. Alice loves her some JavaScript and node.js. | ||
51 | |||
52 | We should allow early experimental work to be written in any language as | ||
53 | well. With the proviso that if it becomes a core part later, it should | ||
54 | get rewritten in a combination of Lua, C, and assembler. | ||
55 | |||
56 | |||
57 | Documentation standards | ||
58 | ----------------------- | ||
59 | |||
60 | This project started life as design documents on a MediaWiki based web | ||
61 | site, using MediaWiki markup. Those design documents where migrated to | ||
62 | the Drupal system that replaced the site. At this point every one | ||
63 | wanted to use a different markup syntax. lol | ||
64 | |||
65 | I solved this by installing a few markup systems, but the majority of it | ||
66 | got written as what Drupal refers to as "simple formatting", which | ||
67 | basically allows the use of certain HTML tags, plus a few nicities. | ||
68 | |||
69 | Eventually code started to get written by me, I put it on GitHub. At | ||
70 | around the same time, I was busy transferring the Team Purple website | ||
71 | from individual web applications to SourceForge. Team Purple are the | ||
72 | developers of the Imprudence and Kokua viewers. Later SourceForge | ||
73 | turned evil, so I started looking for other project hosting options. | ||
74 | GitHub has a wiki part, but they squeeze you into a tiny column in the | ||
75 | middle of the web page, and you can't do colours. BitBucket (the other | ||
76 | major project hosting site used by Team Purple) seems to want to sell | ||
77 | you JIRA, so might also not be suitable. In either case, they both | ||
78 | might turn evil as well. Can't find a decent project hoster, sigh. | ||
79 | |||
80 | It looks like it helps to be generic, instead of constantly converting | ||
81 | between each of these markup formats each time we change hosting system. | ||
82 | All of these markup systems get parsed by active code somewhere at | ||
83 | viewing time, to get translated into HTML+CSS+JavaScript that is sent to | ||
84 | your browser. All of the documents are static. Sure, matrix-RAD | ||
85 | included a worlds first active manual, you could test out matrix-RAD | ||
86 | commands right there in the docs, but we are going a different way this | ||
87 | time. We are no longer living in the web browser, but replacing it with | ||
88 | a virtual world, that might happen to include web pages on prims, but | ||
89 | that's not our main thrust for UI stuff. | ||
90 | |||
91 | Sooooo, to avoid a lot of work, how about we just make the documentation | ||
92 | static HTML web pages, and be done with it? Markup systems are just a | ||
93 | way to make HTML more palatable to ordinary users, but ordinary users | ||
94 | are not writing the design documentiation and such. They all get | ||
95 | translated to HTML, so let's just write raw HTML ourselves. Keep it | ||
96 | simple, no fancy CSS or Javascript shit. So we avoid markup, we avoid | ||
97 | having to translate from markup to markup, and we avoid the rendering | ||
98 | step of translating markup to HTML. We avoid having to parse the | ||
99 | documentation at all, just send it to any old web browser. | ||
100 | |||
101 | In this way, we can just throw the basic documentation up on any old web | ||
102 | server. Enough for people to learn about it, get interested, and get it | ||
103 | up and running. People editing this stuff could just use any HTML | ||
104 | editor if they like, including translating their favourite markup to HTML. | ||
105 | |||
106 | Currently there's ordinary text files as well. A few of those should | ||
107 | stay as ordinary text, but some (or most) could get converted to HTML, | ||
108 | then linked in to the rest. Also, I should link up the existing pages | ||
109 | now, some more internal navigation. | ||
110 | |||
111 | |||
112 | On the other hand, once they have the system running, there's - | ||
113 | |||
114 | Internal documentation standards | ||
115 | -------------------------------- | ||
116 | |||
117 | matrix-RAD included plans for being able to edit down to the code level | ||
118 | from within the web browser running matrix-RAD apps. SL and OS include | ||
119 | world building tools you use from inside the world, including editing of | ||
120 | scripts. So SledjHamr is no different, it will include tools you can | ||
121 | use from inside the world, to edit everything about the world. Which | ||
122 | should include stuff like the matrix-RAD JavaDocs extensions to help | ||
123 | self document code and other fancy things. Obviously this will include | ||
124 | coding standards, and tools to help with those standards. | ||
125 | |||
126 | Once things start being less experimental, then we can decide how that | ||
127 | all works, and the coding standards to suit. | ||
128 | |||