| rev |
line source |
|
seanhalle@6
|
1 <html>
|
|
seanhalle@6
|
2 <head>
|
|
seanhalle@6
|
3 <title>Project tools</title>
|
|
seanhalle@6
|
4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
seanhalle@6
|
5 </head>
|
|
seanhalle@6
|
6
|
|
seanhalle@6
|
7 <body bgcolor="#FFFFFF">
|
|
seanhalle@6
|
8
|
|
seanhalle@6
|
9 <p> </p>
|
|
seanhalle@6
|
10 <h2>Project Tools</h2>
|
|
seanhalle@6
|
11 <p> </p>
|
|
seanhalle@6
|
12 <p>The standard tools used for development on the EQNLang project are:</p>
|
|
seanhalle@6
|
13 <blockquote>
|
|
seanhalle@6
|
14 <p><a href="http://tortoisesvn.tigris.org/">Tortoise SVN</a> -- the revision
|
|
seanhalle@6
|
15 control is done by the Tortoise client</p>
|
|
seanhalle@6
|
16 <p><a href="http://www.netbeans.org/">Netbeans</a> -- preffered for development..
|
|
seanhalle@6
|
17 other tools are fine, but no help will be available to figure out what's not
|
|
seanhalle@6
|
18 working</p>
|
|
seanhalle@6
|
19 <p><a href="http://www.inkscape.org/">inkscape</a> -- an SVG drawing tool. The
|
|
seanhalle@6
|
20 custom graphics used to extend syntax are drawn using inkscape.</p>
|
|
seanhalle@6
|
21 <p> </p>
|
|
seanhalle@6
|
22 </blockquote>
|
|
seanhalle@6
|
23 <p>====</p>
|
|
seanhalle@6
|
24 <p> This part is about project-related things, like tools used, setting up the
|
|
seanhalle@6
|
25 projects, coding style, etc </p>
|
|
seanhalle@6
|
26 <p>=========== </p>
|
|
seanhalle@6
|
27 <p>Using SVN: </p>
|
|
seanhalle@6
|
28 <p>I use Tortoise SVN, after getting burned using netbean's built-in SVN, which
|
|
seanhalle@6
|
29 caused problems.. </p>
|
|
seanhalle@6
|
30 <p> Hostname: eqnlang.svn.sourceforge.net</p>
|
|
seanhalle@6
|
31 <p> Port: 443</p>
|
|
seanhalle@6
|
32 <p> Protocol: HTTPS </p>
|
|
seanhalle@6
|
33 <p> Repository Path: /svnroot/eqnlang/YOURBRANCH/CTOSPlugIns</p>
|
|
seanhalle@6
|
34 <p> For clients that use a URL string: https://eqnlang.svn.sourceforge.net/svnroot/eqnlang/YOURBRANCH/CTOSPlugIns</p>
|
|
seanhalle@6
|
35 <p>==========</p>
|
|
seanhalle@6
|
36 <p> </p>
|
|
seanhalle@6
|
37 <p>IDE: </p>
|
|
seanhalle@6
|
38 <p>Most people on the project use Netbeans, mostly because it's good enough and
|
|
seanhalle@6
|
39 (arguably) easy to learn. I want all of us developers to use the same development
|
|
seanhalle@6
|
40 tool so that everything goes smoothly.. we can share help on the IDE with each
|
|
seanhalle@6
|
41 other, share setups and so on. Of course, if you have an IDE that you really
|
|
seanhalle@6
|
42 want to use, that's up to you, it's just that there won't be much help available
|
|
seanhalle@6
|
43 to you, you'll have to figure out how to make things work with your tool on
|
|
seanhalle@6
|
44 your own. </p>
|
|
seanhalle@6
|
45 <p>If you don't have a strong preference, would you be willing to try netbeans?
|
|
seanhalle@6
|
46 </p>
|
|
seanhalle@6
|
47 <p>Here's the link: http://www.netbeans.org/ to get the latest version </p>
|
|
seanhalle@6
|
48 <p>========= </p>
|
|
seanhalle@6
|
49 <p>Problem with netbeans's built-in SVN client: </p>
|
|
seanhalle@6
|
50 <p>At one point, we were using netbeans's built-in SVN client, but had problems..
|
|
seanhalle@6
|
51 the nbproject folder was included in the SVN, so each developer who checked
|
|
seanhalle@6
|
52 in code would inadvertantly insert the paths for their own harddrive and cause
|
|
seanhalle@6
|
53 everyone else's netbeans to fail. FYI, Most of the problems were in the file:
|
|
seanhalle@6
|
54 nbproject/project.properties</p>
|
|
seanhalle@6
|
55 <p>============= </p>
|
|
seanhalle@6
|
56 <p></p>
|
|
seanhalle@6
|
57 <p>Netbeans projects: </p>
|
|
seanhalle@6
|
58 <p>I have structured the SVN repository in a way that is different from how netbeans
|
|
seanhalle@6
|
59 structures code. The SVN repository has a standard hierarchy of directories.
|
|
seanhalle@6
|
60 However, netbeans likes to have a directory above the one that contains the
|
|
seanhalle@6
|
61 code. It places a special "nbproject" folder there, and puts all the
|
|
seanhalle@6
|
62 code under the "src" folder. So, to work on the code in netbeans,
|
|
seanhalle@6
|
63 first make a "project" directory, then make a "src" and
|
|
seanhalle@6
|
64 a "test" directory under it, then go into the "src" directory..
|
|
seanhalle@6
|
65 there, right click and choose "checkout", which uses the tortoise
|
|
seanhalle@6
|
66 SVN client. Make sure the path is your own, special, branch in the repository,
|
|
seanhalle@6
|
67 this is very important, as a separate branch has been set up in SVN for each
|
|
seanhalle@6
|
68 developer who joins the project. This ensures that each developer has their
|
|
seanhalle@6
|
69 own place to make changes, and I have a chance to look over the code before
|
|
seanhalle@6
|
70 merging it into the trunk. Make the path include the "CTOSPlugIns"
|
|
seanhalle@6
|
71 directory (note the capital "I"), and perform the checkout. When done,
|
|
seanhalle@6
|
72 you will have six folders in your local "src" directory.</p>
|
|
seanhalle@6
|
73 <p>====== </p>
|
|
seanhalle@6
|
74 <p>Create the netbeans projects: </p>
|
|
seanhalle@6
|
75 <p>Right after doing a checkout, you'll need to create a new netbeans project.</p>
|
|
seanhalle@6
|
76 <p> -) Go in to netbeans, right click in the projects area, choose "new project"
|
|
seanhalle@6
|
77 </p>
|
|
seanhalle@6
|
78 <p>-) In the dialog choose "New Java project with Existing Sources" </p>
|
|
seanhalle@6
|
79 <p>-) Click "browse" in the next dialog and navigate to the project folder you
|
|
seanhalle@6
|
80 created earlier, the one that contains the "src" folder that you checked
|
|
seanhalle@6
|
81 out the code into.</p>
|
|
seanhalle@6
|
82 <p> -) After navigating to and choosing the folder, put a name for the project
|
|
seanhalle@6
|
83 in "project name:" box, then click "next" </p>
|
|
seanhalle@6
|
84 <p>-) click "add folder" and select the "src" sub-folder and click "finish"</p>
|
|
seanhalle@6
|
85 <p>At this point, you should be able to build the code (unless I gave you a branch
|
|
seanhalle@6
|
86 that has some skeleton code for you that's not filled in and won't compile..)</p>
|
|
seanhalle@6
|
87 <p>======= </p>
|
|
seanhalle@6
|
88 <p>Libraries:</p>
|
|
seanhalle@6
|
89 <p>At the time of this writing, no external libraries are needed, but that may
|
|
seanhalle@6
|
90 change. If the code doesn't compile because something can't be found, then it's
|
|
seanhalle@6
|
91 probably because a library needs to be added. To add a library, expand the project
|
|
seanhalle@6
|
92 in the projects window (click the "+" sign), so you can see the folders in it
|
|
seanhalle@6
|
93 -- then right-click on the "Libraries" folder. This brings up a menu with options
|
|
seanhalle@6
|
94 for adding a library..</p>
|
|
seanhalle@6
|
95 <p>======= </p>
|
|
seanhalle@6
|
96 <p>Development Interaction </p>
|
|
seanhalle@6
|
97 <p>The method I want to use to develop the language and OS features is to co-develop
|
|
seanhalle@6
|
98 the code. I want to choose the Class names, the directory names, and choose
|
|
seanhalle@6
|
99 how to structure the code. I'll supply Class files with the public method names
|
|
seanhalle@6
|
100 and perhaps some example code. I'll put comments inside the public methods that
|
|
seanhalle@6
|
101 describe the behavior for you. </p>
|
|
seanhalle@6
|
102 <p>Over time, I'll gain experience with you and you may earn my trust to take
|
|
seanhalle@6
|
103 over making more of these decisions for the part you're developing.</p>
|
|
seanhalle@6
|
104 <p> You'll earn my trust through looking at the coding style that's in the code
|
|
seanhalle@6
|
105 and adopting that style the best way you can, for this project.</p>
|
|
seanhalle@6
|
106 <p>========= </p>
|
|
seanhalle@6
|
107 <p>Comment Style</p>
|
|
seanhalle@6
|
108 <p>An easy way to earn more responsibility and ensure that the code you write
|
|
seanhalle@6
|
109 gets merged into the main trunk quickly is to adopt a commenting style that
|
|
seanhalle@6
|
110 makes it easy for me and the other developers to understand how each method
|
|
seanhalle@6
|
111 you write interacts with each other method.</p>
|
|
seanhalle@6
|
112 <p>As you'll soon see in the code, I use comments as a defense against my own
|
|
seanhalle@6
|
113 brain. I forget everything I've done within a few months, so when I look at
|
|
seanhalle@6
|
114 code I wrote before, it's like somebody else wrote it. This caused me to start
|
|
seanhalle@6
|
115 the habit of writing comments in a certain way as a defense. </p>
|
|
seanhalle@6
|
116 <p>When I write comments, I pretend that I am coming to the code fresh, and ask
|
|
seanhalle@6
|
117 myself "what would I want someone to tell me, so that I could understand how
|
|
seanhalle@6
|
118 to modify this code".. that usually includes things that I know at the moment
|
|
seanhalle@6
|
119 about all the pieces that interact.. This is because I can always figure out
|
|
seanhalle@6
|
120 the details by looking at the code, but in order to modify it, I have to understand
|
|
seanhalle@6
|
121 how the pieces fit together. One important case of this is when one data-structure
|
|
seanhalle@6
|
122 is used in a particular way in some other Class. </p>
|
|
seanhalle@6
|
123 <p>The other thing I do is write comments before I write the code that state the
|
|
seanhalle@6
|
124 strategy, or algorithm for the code. This gives me background when I come back
|
|
seanhalle@6
|
125 to it, so I learn why I wrote it the way I did. I always imagine myself asking
|
|
seanhalle@6
|
126 "why did you do it that way?"</p>
|
|
seanhalle@6
|
127 <p>In fact, my code tends to have more lines of comment than lines of code, more
|
|
seanhalle@6
|
128 like novels than programs. This has saved me many times, when I come back to
|
|
seanhalle@6
|
129 change something, I have felt so grateful to myself for putting into the comments
|
|
seanhalle@6
|
130 exactly what I needed to know to change the code.</p>
|
|
seanhalle@6
|
131 <p> I encourage you to try this method if you plan to stay on the project. When
|
|
seanhalle@6
|
132 you come back to change the code, it will give you a happy feeling that you
|
|
seanhalle@6
|
133 put in the effort now, to save yourself headache then. </p>
|
|
seanhalle@6
|
134 <p>It will also make it easier for future developers to use your code, rather
|
|
seanhalle@6
|
135 than getting frustrated and removing it, then re-implementing it. Not to mention
|
|
seanhalle@6
|
136 earn you points.</p>
|
|
seanhalle@6
|
137 <p>========= </p>
|
|
seanhalle@6
|
138 <p>Code Format </p>
|
|
seanhalle@6
|
139 <p>I use the formatting style that I have found to be the easiest for me to see
|
|
seanhalle@6
|
140 the structure of code when I read. I understand if you have a different preference
|
|
seanhalle@6
|
141 that you want to keep. However, if you are willing to try the style I use, it
|
|
seanhalle@6
|
142 is simple to learn: Every line of code has its first character in a multiple
|
|
seanhalle@6
|
143 of 3 column: 0, 3, 6, 9, 12, and so forth. So any text starts on one of those
|
|
seanhalle@6
|
144 columns (except if it is a continuation of a previous line, in which case it's
|
|
seanhalle@6
|
145 whatever looks good to your eye). </p>
|
|
seanhalle@6
|
146 <p>Every curly brace resides in a column exactly in-between: 1, 4, 7, 10, 13.
|
|
seanhalle@6
|
147 So when one looks at the code, all the curly braces line up, and all the code
|
|
seanhalle@6
|
148 lines up, but in different columns. The eye quickly separates the curly braces
|
|
seanhalle@6
|
149 from the code. The curly braces indicate the code structure, so the code structure
|
|
seanhalle@6
|
150 is quickly seen. </p>
|
|
seanhalle@6
|
151 <p>While I am looking over your contribution, there's a good chance that I'll
|
|
seanhalle@6
|
152 be changing the format so that I can see the code structure more easily. You
|
|
seanhalle@6
|
153 may find this to be annoying. I apologise if causes you to feel upset and will
|
|
seanhalle@6
|
154 appreciate if you have patience with the changes.</p>
|
|
seanhalle@6
|
155 <p>======= </p>
|
|
seanhalle@6
|
156 <p>Progression of small project-pieces</p>
|
|
seanhalle@6
|
157 <p> I would like to do the project in a sequence of pieces. Things will change
|
|
seanhalle@6
|
158 over time as each piece is finished, building up on top of previous pieces.
|
|
seanhalle@6
|
159 One thing that won't be obvious to developers is which code choices will fit
|
|
seanhalle@6
|
160 in with future planned additions. I'll need your trust when I request a certain
|
|
seanhalle@6
|
161 structure to the code. </p>
|
|
seanhalle@6
|
162 <p>=======</p>
|
|
seanhalle@6
|
163 <p>That's it, welcome to the EQNLang project!</p>
|
|
seanhalle@6
|
164 <p>Sean</p>
|
|
seanhalle@6
|
165 <p> </p>
|
|
seanhalle@6
|
166 </body>
|
|
seanhalle@6
|
167 </html>
|
