If you've already had a look at our SVN repository, you'll probably be wondering about the age of the trunk. We're not actually using the trunk at all -- releases are extracted from a different repository that is synchronised to the development branch. You can check out the latest development head of by
svn co https://scidavis.svn.sourceforge.net/svnroot/scidavis/branches/development scidavisFor those used to the old subversion repository structure, this has been branched from the old
current_stable branch, which was
renamed to 0.2.4.
Prior to the change of management, bleeding-edge development happened in collaboration with and in the repository (directory: 2.0) of LabPlot. In order to check out the latest version using the SVN command-line client, issue the following command:
svn co https://labplot.svn.sourceforge.net/svnroot/labplot/2.0 scidavis
The collobaration has been featured on KDE.NEWS and there's a Wiki with some summaries of our plans and designs.
Whether this development resumes, or is otherwise used, is up for discussion, as I've only just become aware of this, some 18 months in.
If you're already familiar with C++, Qt and Doxygen, you can safely skip this section; although if you do have a minute, scanning it for bits you don't know yet won't hurt.
SciDAVis is written in the C++ language (not counting some lines of Python code in scidavisrc.py and scidavisUtil.py). This means that fixing bugs and adding sophisticated new features, i.e. anything not (yet) possible with Python, requires at least basic knowledge of C++.
If you want to learn C++, or you’re looking for a reference, here’s some links that might help you:
</dream-in-code>
(tutorials and forums)
Naturally, we can't list every link for a popular topic like C++. Plus, there’s lots and lots of books about C++ like Thinking in C++ by Bruce Eckel, You Can Program in C++: A Programmer's Introduction by Francis Glassborow or Using C++: An Introduction to Programming by Julien Hennefeld, Laura Baker, and Charles Burchard. I haven’t read any of those, but they've received good ratings on Amazon.com. :-)
note from new Website maintainer: The bible for me is Bjarne Stroustrup's The C++ Programming Language, and after you've programmed in C++ for a year or two, you need to read Scott Meyer's Effective C++ books, and Sutter & Alexandrescu's Coding Standards. All of these books are mentioned on Stack Overflow's The Definitive C++ Book Guide and List so perhaps consult that list for a more authoratative recommendation.
If you're a self-learner, the above should be enough to get you going. If not, and books or online resources don’t help, please understand that as much as we would value your contribution, we can't take you by the hand and teach you C++ or how to program. Also, if you’re looking for a forum on C++ in general, asking Google for ``C++ forum'' will give you a lot to choose from. That said, you're welcome to ask questions, including newbie questions, directly related to developing SciDAVis on our mailing list.
SciDAVis makes extensive use of the Qt library originally developed by Trolltech, and then expanded by Nokia and now Digia. We're using it for platform abstraction, signals and slots, the user interface and more; so there’s hardly any part of the code you can understand without knowing about Qt. Luckily, Qt comes with an excellent documentation (also available locally after you've installed Qt). Additionally, there's a large and active community around Qt, see for example the Qt Centre, QtForum.org or this list of OpenSource Qt Applications.
Documenting your code is important, both for maintaining it over any length of time and for helping other developers understand what you’ve done. We're using Doxygen to make this task as easy as possible. Not all of the legacy code is documented yet, but we're continually improving the situation and we’re documenting everything we add. Obviously, any help with this is highly welcome. :-)
As an absolute minimum, you should add short descriptions to class and method declarations as follows:
1 //! A computer built by pan-dimensional, hyper-intelligent beings known to men as mice.
2 class DeepThought
3 {
4 public:
5 //! Return the ultimate answer to life, the universe and everything.
6 int calculateAnswer() const {
7 sleep(7.5e6*365*24*60*60);
8 return 42;
9 }
10 };
Adding some more information is often a good idea, especially when you've put a lot of thought into the design of an interface. Writing down what's on your mind is a lot easier for you than it is for others (or for yourself half a year later) to re-think everything. Here's how:
1 //! A computer built by pan-dimensional, hyper-intelligent beings known to men as mice.
2 /**
3 * Here's where you can elaborate on the usage and design ideas of your class, provide
4 * usage examples etc.
5 */
6 class DeepThought
7 {
8 public:
9 //! Return the ultimate answer to life, the universe and everything.
10 /**
11 * Additional information about the method, its arguments and its return value.
12 */
13 int calculateAnswer() const {
14 sleep(7.5e6*365*24*60*60);
15 return 42;
16 }
17 };
For more information on the syntax and advanced usage, please refer to the Doxygen manual (also available locally after installing Doxygen).
As explained above, we're trying to document the code using Doxygen. The API documentation can be read online for the current release. Or you can generate them for yourself in several different formats by obtaining the source, going to the directory containing the Doxyfile and running Doxygen there.
Before seriously starting to work on a large improvement to SciDAVis, you should announce your plans on the mailing list. This is in your own interest: someone else could already be working on your idea, or later start working on it without knowing about your plans, or it might be foreseeable that your code will be invalidated by someone else's changes. In short, you risk wasting your time if you don't coordinate your work with the rest of us.
If you just want to submit a bugfix or contribute an occasional enhancement, submit your patch here. Either you have an IDE or graphical diff tool for this, or (for Linux, possibly also MacOS X and cygwin) you do
diff -uNr file-or-dir.orig file-or-dir.changed > your.patchin a terminal. This means you have to keep around a copy of the unchanged file or directory. It's easier when you're checking out the source from our subversion repository, which has the additional benefit that it contains the changes we made since the last release. That is, before you start, you do
svn co https://scidavis.svn.sourceforge.net/svnroot/scidavis/branches/development scidavisthen you do your changes, finally generating the patch as follows:
svn diff > your.patch
If you're planning to contribute on a regular basis and you'd like to join the team, introduce yourself and your plans on the scidavis-contributors mailing list or contact project member directly.