Mercurial > cgi-bin > hgwebdir.cgi > POP > oldRepo
diff 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 diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/1__Development/6__Website/ApacheServer/projecttools.html Wed Aug 06 00:16:19 2014 -0700 1.3 @@ -0,0 +1,167 @@ 1.4 +<html> 1.5 +<head> 1.6 +<title>Project tools</title> 1.7 +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 1.8 +</head> 1.9 + 1.10 +<body bgcolor="#FFFFFF"> 1.11 + 1.12 +<p> </p> 1.13 +<h2>Project Tools</h2> 1.14 +<p> </p> 1.15 +<p>The standard tools used for development on the EQNLang project are:</p> 1.16 +<blockquote> 1.17 + <p><a href="http://tortoisesvn.tigris.org/">Tortoise SVN</a> -- the revision 1.18 + control is done by the Tortoise client</p> 1.19 + <p><a href="http://www.netbeans.org/">Netbeans</a> -- preffered for development.. 1.20 + other tools are fine, but no help will be available to figure out what's not 1.21 + working</p> 1.22 + <p><a href="http://www.inkscape.org/">inkscape</a> -- an SVG drawing tool. The 1.23 + custom graphics used to extend syntax are drawn using inkscape.</p> 1.24 + <p> </p> 1.25 +</blockquote> 1.26 +<p>====</p> 1.27 +<p> This part is about project-related things, like tools used, setting up the 1.28 + projects, coding style, etc </p> 1.29 +<p>=========== </p> 1.30 +<p>Using SVN: </p> 1.31 +<p>I use Tortoise SVN, after getting burned using netbean's built-in SVN, which 1.32 + caused problems.. </p> 1.33 +<p> Hostname: eqnlang.svn.sourceforge.net</p> 1.34 +<p> Port: 443</p> 1.35 +<p> Protocol: HTTPS </p> 1.36 +<p> Repository Path: /svnroot/eqnlang/YOURBRANCH/CTOSPlugIns</p> 1.37 +<p> For clients that use a URL string: https://eqnlang.svn.sourceforge.net/svnroot/eqnlang/YOURBRANCH/CTOSPlugIns</p> 1.38 +<p>==========</p> 1.39 +<p> </p> 1.40 +<p>IDE: </p> 1.41 +<p>Most people on the project use Netbeans, mostly because it's good enough and 1.42 + (arguably) easy to learn. I want all of us developers to use the same development 1.43 + tool so that everything goes smoothly.. we can share help on the IDE with each 1.44 + other, share setups and so on. Of course, if you have an IDE that you really 1.45 + want to use, that's up to you, it's just that there won't be much help available 1.46 + to you, you'll have to figure out how to make things work with your tool on 1.47 + your own. </p> 1.48 +<p>If you don't have a strong preference, would you be willing to try netbeans? 1.49 +</p> 1.50 +<p>Here's the link: http://www.netbeans.org/ to get the latest version </p> 1.51 +<p>========= </p> 1.52 +<p>Problem with netbeans's built-in SVN client: </p> 1.53 +<p>At one point, we were using netbeans's built-in SVN client, but had problems.. 1.54 + the nbproject folder was included in the SVN, so each developer who checked 1.55 + in code would inadvertantly insert the paths for their own harddrive and cause 1.56 + everyone else's netbeans to fail. FYI, Most of the problems were in the file: 1.57 + nbproject/project.properties</p> 1.58 +<p>============= </p> 1.59 +<p></p> 1.60 +<p>Netbeans projects: </p> 1.61 +<p>I have structured the SVN repository in a way that is different from how netbeans 1.62 + structures code. The SVN repository has a standard hierarchy of directories. 1.63 + However, netbeans likes to have a directory above the one that contains the 1.64 + code. It places a special "nbproject" folder there, and puts all the 1.65 + code under the "src" folder. So, to work on the code in netbeans, 1.66 + first make a "project" directory, then make a "src" and 1.67 + a "test" directory under it, then go into the "src" directory.. 1.68 + there, right click and choose "checkout", which uses the tortoise 1.69 + SVN client. Make sure the path is your own, special, branch in the repository, 1.70 + this is very important, as a separate branch has been set up in SVN for each 1.71 + developer who joins the project. This ensures that each developer has their 1.72 + own place to make changes, and I have a chance to look over the code before 1.73 + merging it into the trunk. Make the path include the "CTOSPlugIns" 1.74 + directory (note the capital "I"), and perform the checkout. When done, 1.75 + you will have six folders in your local "src" directory.</p> 1.76 +<p>====== </p> 1.77 +<p>Create the netbeans projects: </p> 1.78 +<p>Right after doing a checkout, you'll need to create a new netbeans project.</p> 1.79 +<p> -) Go in to netbeans, right click in the projects area, choose "new project" 1.80 +</p> 1.81 +<p>-) In the dialog choose "New Java project with Existing Sources" </p> 1.82 +<p>-) Click "browse" in the next dialog and navigate to the project folder you 1.83 + created earlier, the one that contains the "src" folder that you checked 1.84 + out the code into.</p> 1.85 +<p> -) After navigating to and choosing the folder, put a name for the project 1.86 + in "project name:" box, then click "next" </p> 1.87 +<p>-) click "add folder" and select the "src" sub-folder and click "finish"</p> 1.88 +<p>At this point, you should be able to build the code (unless I gave you a branch 1.89 + that has some skeleton code for you that's not filled in and won't compile..)</p> 1.90 +<p>======= </p> 1.91 +<p>Libraries:</p> 1.92 +<p>At the time of this writing, no external libraries are needed, but that may 1.93 + change. If the code doesn't compile because something can't be found, then it's 1.94 + probably because a library needs to be added. To add a library, expand the project 1.95 + in the projects window (click the "+" sign), so you can see the folders in it 1.96 + -- then right-click on the "Libraries" folder. This brings up a menu with options 1.97 + for adding a library..</p> 1.98 +<p>======= </p> 1.99 +<p>Development Interaction </p> 1.100 +<p>The method I want to use to develop the language and OS features is to co-develop 1.101 + the code. I want to choose the Class names, the directory names, and choose 1.102 + how to structure the code. I'll supply Class files with the public method names 1.103 + and perhaps some example code. I'll put comments inside the public methods that 1.104 + describe the behavior for you. </p> 1.105 +<p>Over time, I'll gain experience with you and you may earn my trust to take 1.106 + over making more of these decisions for the part you're developing.</p> 1.107 +<p> You'll earn my trust through looking at the coding style that's in the code 1.108 + and adopting that style the best way you can, for this project.</p> 1.109 +<p>========= </p> 1.110 +<p>Comment Style</p> 1.111 +<p>An easy way to earn more responsibility and ensure that the code you write 1.112 + gets merged into the main trunk quickly is to adopt a commenting style that 1.113 + makes it easy for me and the other developers to understand how each method 1.114 + you write interacts with each other method.</p> 1.115 +<p>As you'll soon see in the code, I use comments as a defense against my own 1.116 + brain. I forget everything I've done within a few months, so when I look at 1.117 + code I wrote before, it's like somebody else wrote it. This caused me to start 1.118 + the habit of writing comments in a certain way as a defense. </p> 1.119 +<p>When I write comments, I pretend that I am coming to the code fresh, and ask 1.120 + myself "what would I want someone to tell me, so that I could understand how 1.121 + to modify this code".. that usually includes things that I know at the moment 1.122 + about all the pieces that interact.. This is because I can always figure out 1.123 + the details by looking at the code, but in order to modify it, I have to understand 1.124 + how the pieces fit together. One important case of this is when one data-structure 1.125 + is used in a particular way in some other Class. </p> 1.126 +<p>The other thing I do is write comments before I write the code that state the 1.127 + strategy, or algorithm for the code. This gives me background when I come back 1.128 + to it, so I learn why I wrote it the way I did. I always imagine myself asking 1.129 + "why did you do it that way?"</p> 1.130 +<p>In fact, my code tends to have more lines of comment than lines of code, more 1.131 + like novels than programs. This has saved me many times, when I come back to 1.132 + change something, I have felt so grateful to myself for putting into the comments 1.133 + exactly what I needed to know to change the code.</p> 1.134 +<p> I encourage you to try this method if you plan to stay on the project. When 1.135 + you come back to change the code, it will give you a happy feeling that you 1.136 + put in the effort now, to save yourself headache then. </p> 1.137 +<p>It will also make it easier for future developers to use your code, rather 1.138 + than getting frustrated and removing it, then re-implementing it. Not to mention 1.139 + earn you points.</p> 1.140 +<p>========= </p> 1.141 +<p>Code Format </p> 1.142 +<p>I use the formatting style that I have found to be the easiest for me to see 1.143 + the structure of code when I read. I understand if you have a different preference 1.144 + that you want to keep. However, if you are willing to try the style I use, it 1.145 + is simple to learn: Every line of code has its first character in a multiple 1.146 + of 3 column: 0, 3, 6, 9, 12, and so forth. So any text starts on one of those 1.147 + columns (except if it is a continuation of a previous line, in which case it's 1.148 + whatever looks good to your eye). </p> 1.149 +<p>Every curly brace resides in a column exactly in-between: 1, 4, 7, 10, 13. 1.150 + So when one looks at the code, all the curly braces line up, and all the code 1.151 + lines up, but in different columns. The eye quickly separates the curly braces 1.152 + from the code. The curly braces indicate the code structure, so the code structure 1.153 + is quickly seen. </p> 1.154 +<p>While I am looking over your contribution, there's a good chance that I'll 1.155 + be changing the format so that I can see the code structure more easily. You 1.156 + may find this to be annoying. I apologise if causes you to feel upset and will 1.157 + appreciate if you have patience with the changes.</p> 1.158 +<p>======= </p> 1.159 +<p>Progression of small project-pieces</p> 1.160 +<p> I would like to do the project in a sequence of pieces. Things will change 1.161 + over time as each piece is finished, building up on top of previous pieces. 1.162 + One thing that won't be obvious to developers is which code choices will fit 1.163 + in with future planned additions. I'll need your trust when I request a certain 1.164 + structure to the code. </p> 1.165 +<p>=======</p> 1.166 +<p>That's it, welcome to the EQNLang project!</p> 1.167 +<p>Sean</p> 1.168 +<p> </p> 1.169 +</body> 1.170 +</html>