Pretty soon I'm going to have some code ready that I want to share with the whole world! And my prospective employers who are looking for hard sample of my type and style of work.
For those interested or curious because I know I post a lot, it's a Delaunay triangulation. For those that are curious what that is, it takes a 3D set of points and draws tetrahedra between them but it also ensures at the same time that each tetrahedron is constructed with the spatially closest points.
Now, how do I make this the absolute easiest to understand? The logic of the code, I mean, and how it works, how to use it, etc.
I've decided on using github or Google Code but I'm not sure which one I should actually use. I'm leaning towards github but I use Chromium and I think no one has better computer scientists working for them than Google so...
So, my code is like 1900 lines. I was thinking about using just in-code comments but I'm not even sure how to comment that out.
For example, is it too cluttered to put comments in-between lines of code? Or should I put descriptions of each function above where I define it? 'Cause putting lines in-between code itself seems kind of cluttered and really, really hard to read the code itself.
Also, should I include a README? Basically, my code reads a self-generated point set but I want to modify it someday to read a user file but that's kind of far off and in terms of priority, it's low. It's very low. To me, math is waaaaay more important than UI at this stage of development.
I'm really good with LaTeX and OpenOffice, should I generate a PDF explaining the math of the program? Would it be a worthwhile endeavour? Then I could have a README that'd eventually tell the user that they should generate their own point file and feed it into the software.
And one more thing, my code uses gsl, the GNU Scientific Library. I want my software to be cross-platform (the irony, I know) and as of now, it's pretty much just made for Unix-like environments. gsl works on Windows, right?
I tried googling it last night and people did talk about gsl on Cygwin but is that easy for a Windows users to deal with? I want to make my users happy, fundamentally.
Oh, and my code is pedantic so that means it should be cross-platform, right? I adhere strictly to the standard so any standard compliant compiler should be able to compile my code and I'm assuming Visual Basic or w/e it is Windows users use can compile my code, right?
Or should I write a custom linear algebra routine 'cause I only use gsl or linear algebra XD
Basically, if you were going to try and read 1900 lines of code and understand what it's striving to do, where it hopes to go and how it works, what's the best method for that? I know people are experienced developers here so I was hoping for advice.