Spell Reviewer
- Joined
- May 9, 2006
- Messages
- 3,534
This is a quick insight post about a topic that came out of my review of Paint Bomb v1.00 . My review notes:
And @KILLCIDE is interested in my review in the context of becoming a better programmer. Among my critiques, I consider this the most important point (though possibly not the most relevant in terms of missed points).
When you start up a map to work on it, you can automatically assume some common architectural elements about the map. Some maps might not fit this scheme, but most will.
The capability of making an assumption like this leads to efficiency - any one of us at the hive can open up an open source wc3 ladder map and know exactly how to change something desired, even if we've never seen the map before. That efficiency applies to:
* your peers - other mappers that might want to work on the map with you
* beginners - learning developers that want to understand how to do something you've done the right way
* yourself - in 6 months time when you've forgotten the fine details of your map's composition alraedy.
Being able to draw a simple architectural diagram like the one above is really important in software engineering (including when making GUI triggers!) because it's the core starting point for understanding something complex efficiently.
--
Taking this same concept and applying it to GUI or JASS scripts has one caveat: you'd rarely draw a diagram like the one above for maintainability reasons, because it takes time in and of itself. Here are some tips:
- if you don't have a diagram, you should be able to at least make one
- every missing diagram really must have good, strong documentation in its place, which describes the same thing (examples will come below)
- the "simple" requirement of the diagram must also apply to your triggers/scripts architecture, or you wil have maintainability problems. Sometimes this is justified in the name of performance, but other times, actively detracts from your system's quality.
Key point: modularity plays a role in being able to compose a system into a nice, simple architectural diagram. Modularity aids not only for understanding your system, but also for composition - letting your users augment or remove function that your system logicaly "composes in", rather than builds-in.
--
Let's move on to an example. If you start with a small system and build up, it eventually becomes complex and unwieldy [unless you've architected it carefully!] A diagram for a complex and unmodular system might look like:
And your matching documentation might look like a comment on each module:
- On-cast trigger that creates a fireball. The Periodic trigger moves fireballs.
- Periodic trigger that moves a fireball and deals damage.
If you want to expand this to support different movement behaviors (homing fireball?) and different debuffs (burn damage, on-kill bonus effect, etc), then your diagram quickly becomes overloaded with more "configures" in trigger 1 and more "effects" (after the
--
A more composable example, with better architectural flow might have a logical diagram like this:
Key point: you don't need to actually draw this diagram for your sytem (although you can). The important thing is to at least put a copy of this daigram in your reviewer's brain - usually using documentation text!
Documentation text for this example has more high-level details, but fewer low-level ones. That's desired!
That's all there is to it. Key points:
- have a diagram in your head about how your spells and systems flow
- put that diagram in the head of your reader by documenting the control flow
- over time, you'll get better at keeping your diagram (architecture) at a high level - describing the overarching themes and interactions, rather than small details. Sometimes this is simple (documentation shouldn't specify how much damage the on-hit effect does), and sometimes this is harder and more focused (learning new architectural patterns that permit you to move around data elegantly, composably, and with modularity).
And @KILLCIDE is interested in my review in the context of becoming a better programmer. Among my critiques, I consider this the most important point (though possibly not the most relevant in terms of missed points).
When you start up a map to work on it, you can automatically assume some common architectural elements about the map. Some maps might not fit this scheme, but most will.
The capability of making an assumption like this leads to efficiency - any one of us at the hive can open up an open source wc3 ladder map and know exactly how to change something desired, even if we've never seen the map before. That efficiency applies to:
* your peers - other mappers that might want to work on the map with you
* beginners - learning developers that want to understand how to do something you've done the right way
* yourself - in 6 months time when you've forgotten the fine details of your map's composition alraedy.
Being able to draw a simple architectural diagram like the one above is really important in software engineering (including when making GUI triggers!) because it's the core starting point for understanding something complex efficiently.
--
Taking this same concept and applying it to GUI or JASS scripts has one caveat: you'd rarely draw a diagram like the one above for maintainability reasons, because it takes time in and of itself. Here are some tips:
- if you don't have a diagram, you should be able to at least make one
- every missing diagram really must have good, strong documentation in its place, which describes the same thing (examples will come below)
- the "simple" requirement of the diagram must also apply to your triggers/scripts architecture, or you wil have maintainability problems. Sometimes this is justified in the name of performance, but other times, actively detracts from your system's quality.
Key point: modularity plays a role in being able to compose a system into a nice, simple architectural diagram. Modularity aids not only for understanding your system, but also for composition - letting your users augment or remove function that your system logicaly "composes in", rather than builds-in.
--
Let's move on to an example. If you start with a small system and build up, it eventually becomes complex and unwieldy [unless you've architected it carefully!] A diagram for a complex and unmodular system might look like:
And your matching documentation might look like a comment on each module:
- On-cast trigger that creates a fireball. The Periodic trigger moves fireballs.
- Periodic trigger that moves a fireball and deals damage.
If you want to expand this to support different movement behaviors (homing fireball?) and different debuffs (burn damage, on-kill bonus effect, etc), then your diagram quickly becomes overloaded with more "configures" in trigger 1 and more "effects" (after the
Hit? check) in trigger 2.--
A more composable example, with better architectural flow might have a logical diagram like this:
Key point: you don't need to actually draw this diagram for your sytem (although you can). The important thing is to at least put a copy of this daigram in your reviewer's brain - usually using documentation text!
Documentation text for this example has more high-level details, but fewer low-level ones. That's desired!
JASS:
// The fireball ability consists of an event-hook that creates a
// new fireball; a periodic iterator trigger that manages fireballs
// on each tick; an interface describing how the fireball should
// move; and an interface describing on-hit effects. Fireballs
// can have one movement behavior but many on-hit effects.
//
// The standard behavior is for the event-hook trigger to
// configure the fireball's movement behavior, which defaults to
// "Straight movement". It also configures the array of on-hit
// effects, which defaults to just "[damage]".
//
// The periodic trigger goes through each configured on-hit
// effect before deallocating and runs through it.That's all there is to it. Key points:
- have a diagram in your head about how your spells and systems flow
- put that diagram in the head of your reader by documenting the control flow
- over time, you'll get better at keeping your diagram (architecture) at a high level - describing the overarching themes and interactions, rather than small details. Sometimes this is simple (documentation shouldn't specify how much damage the on-hit effect does), and sometimes this is harder and more focused (learning new architectural patterns that permit you to move around data elegantly, composably, and with modularity).
People should be proud of their code! They should keep it clean and coherent for the benefit of everyone.
