Is it Just Me, or is this Community Stingy About Sharing?

[Inge]

And if you really don't care whether anyone understands your code or not, remember 90% of edits are by the original author - I bet in a couple of months' time *you* won't remember what the hell your code was doing unless you comment it!

[J. M. Pescado]

I don't know about this "middleman" stuff, if you're a good programmer you should be able to explain your work to a common person.

I dunno about explaining it to a COMMON person, unless "the magical computer fairy waves her wand and makes it happen" qualifies as an explanation.

[maxon]

What is needed is the rarer person - the one who stands in the door - the one who is not a programmer, but knows enough about what is going on, who will turn around and translate what the programmer has done/said for those who don't have a clue. AND, the door person, needs to be a technical writer.

Actually, what you want there is a teacher - we do that sort of thing all the time.  The crucial skill is being able to guage the level of understanding and capabilities of your readers.

[Ness]

I don't know about this "middleman" stuff, if you're a good programmer you should be able to explain your work to a common person.

I dunno about explaining it to a COMMON person, unless "the magical computer fairy waves her wand and makes it happen" qualifies as an explanation.

I love that explanation!  I'm sure my students will love hearing explanations along the lines of "the mathematics fairy waves her magic wand and makes it so, just shut up and do it already!".   

[cwykes]

I'm feeling guilty right now that I can't offer any useful help on this.  I can write and I have plenty of time, but I'm a research/analyst type not a techie.  We know enough to be dangerous is the way I think of us "super users".  Anyway I've never done any meshing or even a recolour and I don't have or want all the EPs.  I'll check out the wiki's and see if there are any areas I can contribute on.  I spend a lot of time helping simmers learn and find things... that's a role I like..  If there's a place I should hang out and help... point me at it.

[miros]

I'm terrible at commenting my code, even if I bother to do so at all.  My comments usually just state the obvious like "assigns X to Y" when the code is "x = y;".  I haven't programmed a whole lot though and only know some C.

I don't know about this "middleman" stuff, if you're a good programmer you should be able to explain your work to a common person.

Yes, you should be able to do your own commenting, especially if you "comment as you go."  I.E. get one small thing working and write a sentence that tells what it does and why. 

You also want to code in error checking; "f = fopen()" should be immediately followed by "if ( f == -1 ) return"

In terms of "learning to comment":  Better variable names help!  "x = y" could be anything.  "drawHeight = height / 3" tells you that drawHeight is going to be used to draw something scaled to 1/3 the original size.  That's what you'd put in your comment for people too tired to read the code properly.  Yes, people look at code tired, especially open source projects that they're working on in their own time.

My last boss required lots of comments -- the theory of what you did in the original code or why it doesn't work and how you fixed it for bug fixes.  One of my coworkers laughed his butt off when I said "search for a comment containing the words 'some moronic programs'" when he needed to see a certain bug fix, but he found it.  Between comments and white space, actual code was far less than 1/2 of the line count in most of our source files.

Another important form of commenting is a separate "change notes" file so that testing could quickly see which bugs had been worked on.  That way they don't waste time retesting Bug X that hadn't been fixed or skip testing Bug Y that was only partially fixed.  This is helpful even if you have a bug database!

@dizzy -- there's a py-to-exe utility that will turn your python files into freestanding executables that will pass JMP's "fits on a floppy" test.

[J. M. Pescado]

Yes, you should be able to do your own commenting, especially if you "comment as you go."  I.E. get one small thing working and write a sentence that tells what it does and why.

The problem with that approach is that when I write it, I have no idea whether it actually works or why.

You also want to code in error checking; "f = fopen()" should be immediately followed by "if ( f == -1 ) return"

Pff. That doesn't work. fopen returns NULL on failure, and also requires ARGUMENTS, so the correct response would be something like if( !( f=fopen(blahblahblah) ) { die_horribly(); }

[Orbit]

In reply to the first post in this thread,

I totally agree with all of Jade's points, and I think that there should be a central wiki that is totally user-driven, such as the users submit content, the users vote on what they think the wiki should consist of, how it should be organized, etc. instead of the site administrators making all of the decisions about the wiki. The wiki should be easier to use and easier to find than the currently existing MTS2 wiki.  This wiki should consist of:

• Links and repostings of tutorials already made on various websites
• New tutorials that people write
• Information about the file formats that TS2 uses, information that would help users create new modding tools
• Comments and explanations about various parts of TS2 game files, such as what some BHAVs do in the objects.package of the TS2 games
• General helpful information about various parts of TS2 game files, such as what to do and not do when modding a BHAV in an objects.package
• Any other information that the TS2 modding community would like to be put on the wiki

I strongly emphasize that the database should be a wiki because it is the only way that one can ever hope to achieve a totally user-driven website.  If enough people will support me and help me maintain it, I volunteer to create a wiki on my website and have it serve as the new database for the TS2 modding community.

[dizzy]

@dizzy -- there's a py-to-exe utility that will turn your python files into freestanding executables that will pass JMP's "fits on a floppy" test.

If you mean py2exe, that only works that way if your code is pure Python. If you also need pygtk+gtk+glade+gobject (which is how I get a UI), then you need something like an installer (which fails his no installer rule).

And by "best", you mean "only", right? How's that I/O library coming?

I didn't say "better" than anything else, did I? 

I/O is pretty much complete. At this point, it's a matter of doing a standard tool for parsing your .dat files (i.e. something more or less like sed). And maybe a packer if I actually care about doing compression.

[J. M. Pescado]

...what *IS* a .dat file? I don't remember these files being a part of any TS2 filespec.

[dizzy]

That's what you get when you use the "extract" tool. It doesn't matter what they're called. I just called them that so you can easily clean them up when you're done with them (i.e. "del *.dat").

[eevilcat]

I think the biggest problem is time. Good, user-friendly, technical documentation takes a lot of effort to produce. I've contributed a single tutorial to MTS2 so far and that only got done because I was off work sick for a couple of days and bored. I found that most of the information I needed was already out there but tucked away in various tutorials/threads, odd other bits I figured out myself or already knew. I also find that a lot of the info seems to be step-by-step 'how to do X' with no explanation of the bigger picture. As a programmer I've always wanted to understand why I'm doing something and how it works, not just blindly follow instructions.

(I've always commented my code/used sensible variable names etc, but I've mainly worked in teams - if it's well-written you don't get bugged by 'what', 'how', 'why' questions every five minutes.)

[miros]

Yes, you should be able to do your own commenting, especially if you "comment as you go."  I.E. get one small thing working and write a sentence that tells what it does and why.

The problem with that approach is that when I write it, I have no idea whether it actually works or why.

Even more important to comment as you go.  Write a comment about what you intend it to do, write your first attempt at the code.  If it works, great.  If it doesn't, you compare your code to your intentions and fix the discrepancy.  I don't go as far as "write the whole program in pseudo code or comments first, then fill in the code," but some people do!

You also want to code in error checking; "f = fopen()" should be immediately followed by "if ( f == -1 ) return"

Pff. That doesn't work. fopen returns NULL on failure, and also requires ARGUMENTS, so the correct response would be something like if( !( f=fopen(blahblahblah) ) { die_horribly(); }

a) I have too many languages in my head.  Some languages return NULL if the file didn't open.  Some return -1.  That's the purpose of context sensitive help.  Click fopen, press F1, you get all the info you could possibly need.
b) It's easier for most people to read if the fopen is on one line and the error check is on another.
c) I used return as an example.  Technically, it should be "throw();" and there should be a whole series of "try{}catch{}" statements in the routines that call it.  But at the level we're discussing, simply having the error check in there is the important thing.  Too many people would write that routine assuming the filename is valid, exists, etc., and never put in the "if (!f) returnorthrowordiehorribly();"  Unfortunately, several of those people work for EA/Maxis.
d) You probably don't want an often-used/low-level routine to "diehorribly."  This leads to unexpected program termination (i.e. crashes), corrupt files, etc. because the routines that called the low-level routine never got a chance to clean up after themselves.

That's what you get when you use the "extract" tool. It doesn't matter what they're called. I just called them that so you can easily clean them up when you're done with them (i.e. "del *.dat").

Suggestion: optionally use the 4 letter "resource type" (if it's composed of printable characters) as the suffix on the extracted files.

I strongly emphasize that the database should be a wiki because it is the only way that one can ever hope to achieve a totally user-driven website.  If enough people will support me and help me maintain it, I volunteer to create a wiki on my website and have it serve as the new database for the TS2 modding community.

I think a central repository of links to existing stuff would be more helpful.  Possibly include a comment on whether the info is correct/wrong/outdated/wrongheaded.

[dizzy]

That's what you get when you use the "extract" tool. It doesn't matter what they're called. I just called them that so you can easily clean them up when you're done with them (i.e. "del *.dat").

Suggestion: optionally use the 4 letter "resource type" (if it's composed of printable characters) as the suffix on the extracted files.

Feel free to rewrite the code.