Best way to distribute software?

[MutantJohn]

Hello All,

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.

[whiteflags]

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...

It's up to you.

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.

Normally, important parts, like functions, have a comment block before them that explains in plain english what it does, how it is meant to be called (in terms of pre and post conditions, for example, buffer != NULL), and what is returned.

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.

If you have something to say about a section of code, just put it above or below and add adequate blank lines. Don't think too hard.

Doxygen can read uncommented code if you want to quickly get and distribute documentation in HTML or other formats. Poke around the manual, try the program out, and see if it helps at all.

Also, should I include a README

A readme doesn't have to be complex, and even the smallest projects could use one. Talk about the license you put the code under, talk about what it is, mention how to contact you, etc.

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?

It stands a pretty good chance; did you have the chance to test it on multiple platforms?

[MutantJohn]

Thank you very much for the advice. Makes me feel a lot better.

Okay, now I have an even more important question. How do I write a Makefile that'll work on both Linux and Windows?

Cygwin is a requirement to run this software on Windows and I've never once used it.

This is my Makefile as is :

MKFILE    = Makefile


GCC       = g++ -g -O3 -Wall -std=c++11 -Wextra -lpthread -pedantic `pkg-config --cflags --libs gsl`


CSOURCE   = main.cpp tetra.cpp tree.cpp neighbour.cpp delaunay.cpp
CHEADER   = structures.h
OBJECTS   = ${CSOURCE:.cpp=.o}
EXECBIN   = regulus


all : ${EXECBIN}


${EXECBIN} : ${OBJECTS}
	${GCC} -o $@ ${OBJECTS} -lm


 
%.o : %.cpp


	${GCC} -c $<




clean :
	- rm ${OBJECTS} ${EXECBIN}




again :
	${MAKE} clean all

How would I even begin to make this work on a non-Linux system? Like, how do I know what to call the C++ compiler? Do I let the user specify it?

[Epy]

Pretty sure it'd work on anything that both pthreads and GSL exist on...

[Epy]

Related to my previous comment, what exactly are you using from GSL? Can you write your own, or use something from a more specific library? Also, it doesn't look like GSL depends on pthreads, so I'm guessing you're using it yourself. Have you considered using C++11/C11 threads, or another library that supports cross-platform threading?

[Elysia]

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.

Both. Divide your code into sections with a leading comment that explains what the section does. A section can be a function, too, and if so, document the parameters, return and pre- and post conditions. The more info you can provide, the better.

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.

Yes, you should. If nothing else, say how to build your code and how to use the program.

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.

You are free to discuss the mathematics, of course, if you think you can do it in a good way. Otherwise you could just refer to some good source for those who don't know.

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.

IF they know Linux, then yes. Otherwise, no. It would be an entirely new world since Cygwin seeks to emulate Linux under Windows.
In Windows, it's pretty much standard to use Visual Studio to compile C++ code. You should seek to provide this alternative to users.

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?

In theory, if you stick to the standard and portable libraries, then it should work under any platform. Reality isn't so nice, however, but it's a good start. You need to test it under each platform and with all compilers you want it to work with to make sure it works properly. Different compilers support different subsets of the standard (especially C++11). Different compilers also differ in how nice they are. G++ is much stricter than Visual C++ when it comes to templates, and even has a couple of bugs when it comes to some features, for example. Some things, like auto-generated move constructor/assignment operator are not even implemented in Visual C++! Finally, different platforms have different quirks. In Linux, spawning processes in very fast, but in Windows, it's very slow, for example.