Source Code Level Documentation

[AskKrabbe]

Hi fellow developers,

I want to introduce some of you to literal programming which I use for my personal projects with much success.

I know you all like doxygen since you don't need to do anything about sourcecode documentation when you use this system ?!

This seems to be the attitude of most open software developers. The result of this attitude is a huge, well formatted tree of html code that is an exact copy of the pure C++ source code without any or quite few commenting lines.

Don't you capture yourself sometimes, touching one year old code, pondering about what you might have though, typing this hieroglyphs and you cannot even think about this code to do what it has been doing until the last update yesterday ?

Anyway I ask this question when I view a file like "src/unit_csv.h":

Code: Select all

CSVRow LookupUnitRow(std::string name, std::string faction);
extern vector<unsigned int> AddMeshes(std::vector<Mesh*>&xmeshes, float&randomstartframe, float&randomstartseconds, float unitscale, std::string meshes,int faction,Flightgroup *fg);

Nice, and completely senseless. This is really the complete file.

Besides the function definitions in the *.cpp files don't look much better.

I would recommend using Knuth's CWEB and I can assist you in doing so but before I start hacking your source code I want to discuss this topic with you so feel free to answer to this thread ...

[dandandaman]

You'll probably need to wait a bit to get a definitive response...our lead developer is taking a short break from proceedings

Dan.a

[rewpparo]

I couldn't agree more actually... It's hard when you know nothing about the insides of the project to know where to start of what things are doing.
I started to stick my noze in the sources, and I have to start from the main loop to figure out how things are done in there. Some object seem to contain multiple game systems, so that makes it even harder to get a clear picture of where to look to get what you want.
A well documented code, especially in open source where people are expected to join and help, is a must have.

[jackS]

While Danny may be a wonderful human being, and a high-performance coding machine he has not, for all the classes taken and nagging in the world by those around him taken up a habit of verbose commenting of his code, nor the construction & maintenance of overarching documentation (and the vast bulk of the lines in the VS source tree are his).

So be it. We're all indebted to him. At some point, we can repay him by commenting his code for him, and by documenting the project so that more people can assist him more easily.

Add to this the evolutionary, rather than designed, nature of much of VS development, and, yes, it's not all that inviting (and was of some amusement to the prof teaching my software engineering course). I have some plans that I'll be able to get some degree of code documenting done this summer (as both Danny and I are in the same city for the first time in 2 years), but I hope that people may forgive me if, after workdays often spent modifying the guts of cycle-accurate architectural performance simulators, documenting someone else's code is not often my first choice for the evening's contribution to VS.

[AskKrabbe]

I never wanted to affront any of these creative code cannons who make vegastrike or any other open source project living and running for years now. Just that I want to share some experiences and thus might bring in my abilities in documenting code, though I don't think that I can do more than 5-10% of the documentation my own.

But the last years of software development lead me into this literal programming stuff and I really would appreciate if more software projects would choose this route. Finally its more a habit to be trained and a few symbolic constructs to fiddle with, to get code documented really well and so to help your own code to live longer and be more powerfull from the time on when it left your fingers.

I have done a syntax example (not very well elaborated yet) for the unit_csv.cpp and unit_csv.h file just to show how fast and simple a program module can be converted to produce a real code documentation. This code documentation is more paper oriented though, since the output format is TeX. It's not HTML and it is not easy to make HTML code from it though it isn't impossible. But most programs will gain much from TeX DVI output format and you can produce a well linked PDF file too.

If you want to view the example send me a
[url]mailto:<ikrabbe.ask@web.de>[/url]