seanhalle@6:
seanhalle@6:
The standard tools used for development on the EQNLang project are:
seanhalle@6:seanhalle@6:seanhalle@6:Tortoise SVN -- the revision seanhalle@6: control is done by the Tortoise client
seanhalle@6:Netbeans -- preffered for development.. seanhalle@6: other tools are fine, but no help will be available to figure out what's not seanhalle@6: working
seanhalle@6:inkscape -- an SVG drawing tool. The seanhalle@6: custom graphics used to extend syntax are drawn using inkscape.
seanhalle@6:seanhalle@6:
====
seanhalle@6:This part is about project-related things, like tools used, setting up the seanhalle@6: projects, coding style, etc
seanhalle@6:===========
seanhalle@6:Using SVN:
seanhalle@6:I use Tortoise SVN, after getting burned using netbean's built-in SVN, which seanhalle@6: caused problems..
seanhalle@6:Hostname: eqnlang.svn.sourceforge.net
seanhalle@6:Port: 443
seanhalle@6:Protocol: HTTPS
seanhalle@6:Repository Path: /svnroot/eqnlang/YOURBRANCH/CTOSPlugIns
seanhalle@6:For clients that use a URL string: https://eqnlang.svn.sourceforge.net/svnroot/eqnlang/YOURBRANCH/CTOSPlugIns
seanhalle@6:==========
seanhalle@6:seanhalle@6:
IDE:
seanhalle@6:Most people on the project use Netbeans, mostly because it's good enough and seanhalle@6: (arguably) easy to learn. I want all of us developers to use the same development seanhalle@6: tool so that everything goes smoothly.. we can share help on the IDE with each seanhalle@6: other, share setups and so on. Of course, if you have an IDE that you really seanhalle@6: want to use, that's up to you, it's just that there won't be much help available seanhalle@6: to you, you'll have to figure out how to make things work with your tool on seanhalle@6: your own.
seanhalle@6:If you don't have a strong preference, would you be willing to try netbeans? seanhalle@6:
seanhalle@6:Here's the link: http://www.netbeans.org/ to get the latest version
seanhalle@6:=========
seanhalle@6:Problem with netbeans's built-in SVN client:
seanhalle@6:At one point, we were using netbeans's built-in SVN client, but had problems.. seanhalle@6: the nbproject folder was included in the SVN, so each developer who checked seanhalle@6: in code would inadvertantly insert the paths for their own harddrive and cause seanhalle@6: everyone else's netbeans to fail. FYI, Most of the problems were in the file: seanhalle@6: nbproject/project.properties
seanhalle@6:=============
seanhalle@6: seanhalle@6:Netbeans projects:
seanhalle@6:I have structured the SVN repository in a way that is different from how netbeans seanhalle@6: structures code. The SVN repository has a standard hierarchy of directories. seanhalle@6: However, netbeans likes to have a directory above the one that contains the seanhalle@6: code. It places a special "nbproject" folder there, and puts all the seanhalle@6: code under the "src" folder. So, to work on the code in netbeans, seanhalle@6: first make a "project" directory, then make a "src" and seanhalle@6: a "test" directory under it, then go into the "src" directory.. seanhalle@6: there, right click and choose "checkout", which uses the tortoise seanhalle@6: SVN client. Make sure the path is your own, special, branch in the repository, seanhalle@6: this is very important, as a separate branch has been set up in SVN for each seanhalle@6: developer who joins the project. This ensures that each developer has their seanhalle@6: own place to make changes, and I have a chance to look over the code before seanhalle@6: merging it into the trunk. Make the path include the "CTOSPlugIns" seanhalle@6: directory (note the capital "I"), and perform the checkout. When done, seanhalle@6: you will have six folders in your local "src" directory.
seanhalle@6:======
seanhalle@6:Create the netbeans projects:
seanhalle@6:Right after doing a checkout, you'll need to create a new netbeans project.
seanhalle@6:-) Go in to netbeans, right click in the projects area, choose "new project" seanhalle@6:
seanhalle@6:-) In the dialog choose "New Java project with Existing Sources"
seanhalle@6:-) Click "browse" in the next dialog and navigate to the project folder you seanhalle@6: created earlier, the one that contains the "src" folder that you checked seanhalle@6: out the code into.
seanhalle@6:-) After navigating to and choosing the folder, put a name for the project seanhalle@6: in "project name:" box, then click "next"
seanhalle@6:-) click "add folder" and select the "src" sub-folder and click "finish"
seanhalle@6:At this point, you should be able to build the code (unless I gave you a branch seanhalle@6: that has some skeleton code for you that's not filled in and won't compile..)
seanhalle@6:=======
seanhalle@6:Libraries:
seanhalle@6:At the time of this writing, no external libraries are needed, but that may seanhalle@6: change. If the code doesn't compile because something can't be found, then it's seanhalle@6: probably because a library needs to be added. To add a library, expand the project seanhalle@6: in the projects window (click the "+" sign), so you can see the folders in it seanhalle@6: -- then right-click on the "Libraries" folder. This brings up a menu with options seanhalle@6: for adding a library..
seanhalle@6:=======
seanhalle@6:Development Interaction
seanhalle@6:The method I want to use to develop the language and OS features is to co-develop seanhalle@6: the code. I want to choose the Class names, the directory names, and choose seanhalle@6: how to structure the code. I'll supply Class files with the public method names seanhalle@6: and perhaps some example code. I'll put comments inside the public methods that seanhalle@6: describe the behavior for you.
seanhalle@6:Over time, I'll gain experience with you and you may earn my trust to take seanhalle@6: over making more of these decisions for the part you're developing.
seanhalle@6:You'll earn my trust through looking at the coding style that's in the code seanhalle@6: and adopting that style the best way you can, for this project.
seanhalle@6:=========
seanhalle@6:Comment Style
seanhalle@6:An easy way to earn more responsibility and ensure that the code you write seanhalle@6: gets merged into the main trunk quickly is to adopt a commenting style that seanhalle@6: makes it easy for me and the other developers to understand how each method seanhalle@6: you write interacts with each other method.
seanhalle@6:As you'll soon see in the code, I use comments as a defense against my own seanhalle@6: brain. I forget everything I've done within a few months, so when I look at seanhalle@6: code I wrote before, it's like somebody else wrote it. This caused me to start seanhalle@6: the habit of writing comments in a certain way as a defense.
seanhalle@6:When I write comments, I pretend that I am coming to the code fresh, and ask seanhalle@6: myself "what would I want someone to tell me, so that I could understand how seanhalle@6: to modify this code".. that usually includes things that I know at the moment seanhalle@6: about all the pieces that interact.. This is because I can always figure out seanhalle@6: the details by looking at the code, but in order to modify it, I have to understand seanhalle@6: how the pieces fit together. One important case of this is when one data-structure seanhalle@6: is used in a particular way in some other Class.
seanhalle@6:The other thing I do is write comments before I write the code that state the seanhalle@6: strategy, or algorithm for the code. This gives me background when I come back seanhalle@6: to it, so I learn why I wrote it the way I did. I always imagine myself asking seanhalle@6: "why did you do it that way?"
seanhalle@6:In fact, my code tends to have more lines of comment than lines of code, more seanhalle@6: like novels than programs. This has saved me many times, when I come back to seanhalle@6: change something, I have felt so grateful to myself for putting into the comments seanhalle@6: exactly what I needed to know to change the code.
seanhalle@6:I encourage you to try this method if you plan to stay on the project. When seanhalle@6: you come back to change the code, it will give you a happy feeling that you seanhalle@6: put in the effort now, to save yourself headache then.
seanhalle@6:It will also make it easier for future developers to use your code, rather seanhalle@6: than getting frustrated and removing it, then re-implementing it. Not to mention seanhalle@6: earn you points.
seanhalle@6:=========
seanhalle@6:Code Format
seanhalle@6:I use the formatting style that I have found to be the easiest for me to see seanhalle@6: the structure of code when I read. I understand if you have a different preference seanhalle@6: that you want to keep. However, if you are willing to try the style I use, it seanhalle@6: is simple to learn: Every line of code has its first character in a multiple seanhalle@6: of 3 column: 0, 3, 6, 9, 12, and so forth. So any text starts on one of those seanhalle@6: columns (except if it is a continuation of a previous line, in which case it's seanhalle@6: whatever looks good to your eye).
seanhalle@6:Every curly brace resides in a column exactly in-between: 1, 4, 7, 10, 13. seanhalle@6: So when one looks at the code, all the curly braces line up, and all the code seanhalle@6: lines up, but in different columns. The eye quickly separates the curly braces seanhalle@6: from the code. The curly braces indicate the code structure, so the code structure seanhalle@6: is quickly seen.
seanhalle@6:While I am looking over your contribution, there's a good chance that I'll seanhalle@6: be changing the format so that I can see the code structure more easily. You seanhalle@6: may find this to be annoying. I apologise if causes you to feel upset and will seanhalle@6: appreciate if you have patience with the changes.
seanhalle@6:=======
seanhalle@6:Progression of small project-pieces
seanhalle@6:I would like to do the project in a sequence of pieces. Things will change seanhalle@6: over time as each piece is finished, building up on top of previous pieces. seanhalle@6: One thing that won't be obvious to developers is which code choices will fit seanhalle@6: in with future planned additions. I'll need your trust when I request a certain seanhalle@6: structure to the code.
seanhalle@6:=======
seanhalle@6:That's it, welcome to the EQNLang project!
seanhalle@6:Sean
seanhalle@6:seanhalle@6: seanhalle@6: