Documentation on the Code

[mpettitt]

If the project is to survive, you need "newbies tinkering with a few values". Sorry, but it's the case with open source projects. If that means dedicating developer time to documenting all the existing code, so be it.
It also means documenting all new features fully, getting a manual which mentions things like the cheat dialog and the meanings of the settings in the patch dialog.

Yes, it's hard work, and it isn't getting new flashy features into the system, but, to be frank, most people who end up using the program want to know how to use the existing features, not to be told about features that will be coming in the future...

[ChrisCF]

Exactly. A feature is of no use to anyone if nobody knows how to use it.

Good documentation can make or break a project.

[dominik81]

Just to get this straight first: We're talking about code documentation, not documenting features. No one doubts that all the features of the game should be explained to the full extend in a manual.

If the project is to survive, you need "newbies tinkering with a few values".

Here's an excellent example of what I mean: Take a look at this bug report on SourceForge. I could spend hours trying to fix this "bug" and still wouldn't come up with a solution. The reason?
Here. This "newbie tinkering with the source" apparently applied a few patches here and there, not knowing what he's doing. It's no surprise that his savegame is broken now.

My point is: People who don't know how to code shouldn't mess with the source. If they want to, they should learn C/C++ on a smaller project, maybe an own project, first. Active developers are not C tutors.

New developers are certainly always welcome. But they should at least know the basics about the language they're coding in. And they should know what a compiler is.

[ChrisCF]

OK, but a feature is still of no use, if nobody knows how it works. And elitism is still elitism. You don't know whether perhaps those patches weren't things he changed, but perhaps from one of the major patch writers here. Of course, it's still possible that he broke his savegame because he broke his game himself.

[mpettitt]

It's even possible that the patches were buggy because of a slight error in following the undocumented code...

[thorkia]

I would have to agree with the developers at this point.

While I like well documented code, as an ameteur programmer (self-taught), I was able to find my way thru the code quite quickly.

The developers have used very descriptive variable and function names making things really easy to understand. Well, except that saveload stuff <shudder>

I would rather have the team spend time adding new code, and re-writing the old stuff to support more functionality. All the new code I have seen is really well documented. Just document the new and changed stuff only.

But that's my opinion

[Darkvater]

I also think the game is really well structured. I joined the project right at the beginning where it was all like the old code. Not messy, props to Ludde, but all written in his own vision which not all of us share, let even know. So yes, in the beginning it is really difficult to find out how things work. But after a few hours you get a feeling for the approach, the style, and it all becomes clear.

My personal feeling is that yes, old code should also need comments. But only when it is touched. In situations where a bugfix is applied, or a new feature is added that extends the existing code, the developer, or coder looks through the code to understand it. When he does, that is the best point to comment the code. He/she understands it, and it's not much of an additional effort to put in some lines, easing it for other people, or maybe even him/her-self at a later point.

I think that would be the best, least time-wasting approach.

[matt_sonyc]

Is a documentation on the variable structure of the game available? Or is it a silly question?