blob: f8685bea71ab9e1f5dc38be4db50a952a267847e (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
<TITLE>ACE Beginners' Guide</TITLE>
<BODY text = "#000000" link="#000fff" vlink="#ff0f0f" bgcolor="#ffffff">
<CENTER><H1>The Beginners' Guide to ACE</H1></CENTER>
<P>
This site is dedicated to developing a set of tutorials to get ACE
newcomers up to speed with the framework. For now, this will be
limited strictly to ACE matters but I'm not opposed to setting up a
separate area for TAO. In fact, I encourage it! <P>
Here are some general guidelines for creating tutorials:
<P>
<UL>
<LI> Choose a topic that you know very well or are just learning.
<P>
This isn't really a conflict...
<P>
If you know a topic very well, you're likely to know what is most
important to the novice and what can be left until later. If you're
just learning a topic, then you know what questions you have that
must be answered before you can continue.
<P>
<LI> Keep it simple.
<P>
Don't try to use a lot of really cool ACE features along the way. Stick
to the basic stuff and show that. Try to use a minimum of ACE objects
that are not the direct target of the tutorial.
<P>
(For instance, don't get all caught up in ACE_Singleton<> if you're
trying to show how to use an ACE_Reactor.)
<P>
If you want to show something really cool that happens to depend on
another ACE feature, do a tutorial on that other feature first! I've
found that folks will tend to get stuck on *anything* they don't
understand even if it isn't directly relevant to what you're trying
to teach.
<P>
<LI> Document the heck out of it!
<P>
There's no such thing as too much documentation. Don't worry about
repeating yourself along the way. Assume that the reader knows nothing
at all about the topic at hand and explain even the parts that you feel
are painfully obvious.
<P>
If you feel that sticking a bunch of comments in the code makes it harder
to read then stick in a label and document at the end of the file or
something. Alternately, create both a well-documented version and a
sparsely-documented version. Then folks can choose between 'em.
<P>
<LI> Over-teach it.
<P>
If there's a tutorial created for a topic that you feel strong in,
create another one anyway. Everybody tends to code a little differently.
Perhaps your tutorial style will "feel" better to some newcomers
than an existing tutorial. You won't hurt anybody's feelings if
you present the same material in a different way.
<P>
<LI> Steal existing code.
<P>
The ultimate form of code reuse :-) Seriously... grab one or more
of the existing ACE tests or examples. Then strip it down to the
bare bones & add heaps of comments. I don't think the software-police
will be coming after anyone for that!
</UL>
<P>
If this thing takes off, I'll start to organize the tutorials into
groups. For now, lets concentrate on quantity & quality. Organization
can come later...
<P>
<A HREF="tutorials">Follow this link to the tutorials...</A>
|
