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