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