Alternative debug annotation example, plus explanation of why I think it needs changed like this
This commit is contained in:
parent
8d022a332a
commit
4074699766
68
TUTORIAL.org
68
TUTORIAL.org
|
@ -388,27 +388,61 @@ point at all... it would be simpler to just provide a comment syntax.
|
||||||
However, annotations can be used for more than just comments.
|
However, annotations can be used for more than just comments.
|
||||||
They can also be used for debugging or other development-tool-oriented
|
They can also be used for debugging or other development-tool-oriented
|
||||||
data.
|
data.
|
||||||
For instance, here is some data game data annotated with who the
|
|
||||||
"project owner" is of each object.
|
# 2019-08-18 14:10:15 tonyg -- Similarly, I am uncomfortable with this
|
||||||
|
# example. It seems to me that the annotations are indeed domain data,
|
||||||
|
# just in a different domain of "project management" rather than the
|
||||||
|
# domain of "NPC data sheet"! Annotations are intended for the domain
|
||||||
|
# of *programming and debugging software systems* -- they're intended
|
||||||
|
# for reflective use. You use them when you're thinking about
|
||||||
|
# preserves artifacts per se, rather than anything about the domain of
|
||||||
|
# the data encoded within a given preserves artifact.
|
||||||
|
#
|
||||||
|
# Maybe a good example is something like an HTTP API? You could
|
||||||
|
# annotate a response with the time it took to be produced in
|
||||||
|
# milliseconds. I'll sketch something out.
|
||||||
|
#
|
||||||
|
# -- original text from dustyweb follows --
|
||||||
|
|
||||||
|
# For instance, here is some data game data annotated with who the
|
||||||
|
# "project owner" is of each object.
|
||||||
|
|
||||||
|
# #+BEGIN_SRC preserves
|
||||||
|
# <NpcCatalog
|
||||||
|
# "Monsters"
|
||||||
|
# #set{@<ProjectLead Alyssa>
|
||||||
|
# {name: "Ogre",
|
||||||
|
# spriteSheet: #base64{T2dyZSBzcHJpdGVzIGdvIGhlcmU=},
|
||||||
|
# attributes: #set{biped, brute, rage, clumsy}},
|
||||||
|
# @<ProjectLead Ben>
|
||||||
|
# {name: "Jackal",
|
||||||
|
# spriteSheet: #base64{V2l0Y2ggc3ByaXRlcyBnbyBoZXJl},
|
||||||
|
# attributes: #set{quadruped, swift, pack-animal, weak}}}>
|
||||||
|
# #+END_SRC
|
||||||
|
|
||||||
|
# Each monster descrived in the set is annotated with a =ProjectLead=
|
||||||
|
# record.
|
||||||
|
# While useful information used by the game company's organization
|
||||||
|
# system, it doesn't particularly matter when reading in the data
|
||||||
|
# just as code.
|
||||||
|
|
||||||
|
For instance, here's a reply from an HTTP API service running in
|
||||||
|
"debug" mode annotated with the time it took to produce the reply and
|
||||||
|
the internal name of the server that produced the response:
|
||||||
|
|
||||||
#+BEGIN_SRC preserves
|
#+BEGIN_SRC preserves
|
||||||
<NpcCatalog
|
@<ResponseTime <Milliseconds 64.4>>
|
||||||
"Monsters"
|
@<BackendServer "humpty-dumpty.example.com">
|
||||||
#set{@<ProjectLead Alyssa>
|
<Success
|
||||||
{name: "Ogre",
|
<Employees [
|
||||||
spriteSheet: #base64{T2dyZSBzcHJpdGVzIGdvIGhlcmU=},
|
<Employee "Alyssa P. Hacker" #set{<Role Programmer>, <Role Manager>}, <Date 2018, 1, 24>>
|
||||||
attributes: #set{biped, brute, rage, clumsy}},
|
<Employee "Ben Bitdiddle" #set{<Role Programmer>}, <Date 2019, 2, 13>> ]>>
|
||||||
@<ProjectLead Ben>
|
|
||||||
{name: "Jackal",
|
|
||||||
spriteSheet: #base64{V2l0Y2ggc3ByaXRlcyBnbyBoZXJl},
|
|
||||||
attributes: #set{quadruped, swift, pack-animal, weak}}}>
|
|
||||||
#+END_SRC
|
#+END_SRC
|
||||||
|
|
||||||
Each monster descrived in the set is annotated with a =ProjectLead=
|
The annotations aren't related to the data requested, which is all
|
||||||
record.
|
about "employees"; instead, they're about the systems that produced
|
||||||
While useful information used by the game company's organization
|
the response. You could say they're in the domain of "debugging"
|
||||||
system, it doesn't particularly matter when reading in the data
|
instead of the domain of "employees".
|
||||||
just as code.
|
|
||||||
|
|
||||||
* Conclusions
|
* Conclusions
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue