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