Slashdot Mirror

http://wiki.uqm.stack.nl/Supox...

Unzervalt!

1992 - Star Control 2, the Sylandro

Gas giant, not brown dwarf, but close enough.

The Slylandro are the only known race whose homeworld, which they call Source, is a Gas Giant.

They are essentially sapient bags of gas (and a limited quantity of solid and/or liquid) that float through their homeworld's atmosphere.

They evolved from simple, unimodular consumers that thrived in atmospheric convection currents. Originally mindless but social creatures, they developed language to better coordinate efforts to herd their food source into dense concentrations. Source has a great biodiversity for a gas giant—hundreds of species, some producers, others consumers, hunters or parasites—but the Slylandro claim to be the only ones to have evolved intelligence.

When I was talking about comments, I was mostly referring to comments that described the functionality of internal code. In these cases, the comments are typically embedded right with the code, so the locality of that sort of documentation isn't a problem.

For external documentation... I think that would tend to be a per-company or per-project issue. If I was working on code that required external documentation, I'd generally recommend keeping it in the source files using Doxygen or something like that to auto-generate the documentation from specially-formatted comments. It seems a lot more practical to me to keep the documentation tied to the source code for precisely the reasons you imply - if it's separated, it's too easy to let them get out of sync.

I want my seductive, blue skinned, space babes

That way the just go collect the plastic and make more of themselves until the ocean is clean.

Of course we may run into the Slylandro problem.
http://wiki.uqm.stack.nl/Probe

Could just as easily be a planet with spiders so lovable they caused an integer overflow in their own nature and wrapped around to pure evil.

There are plenty of software documentation sets, tutorials, etc, like this one (selected at random), that have Step 0, Step 1, etc.

And that example illustrates the usual reason for starting with step 0: The "zero" step is determining your initial state before you start doing anything. In this case, it's determining whether you should bother going on to step 1, which is pretty common. It's also common to use step 0 to list the material needed by the task.

Probably the most common real-world example is cooking recipes, which typically start with a list of ingredients. That "step" is typically not numbered, but sometimes the actual "steps" to create the food are numbered starting with 1. Or they're just in separate paragraphs, since numbering them isn't actually very useful to carry out the task. In any case, the ingredient list is usually typographically different than the rest of the recipe, and is a description of the required initial state, so it's natural to call it "step 0".

There are plenty of software documentation sets, tutorials, etc, like this one (selected at random), that have Step 0, Step 1, etc. I think it's an attempt to be clever, in that offsets start with zero, and this is documentation about computer stuff, being read by developers. But items in a list, intended to be read by humans, shouldn't be represented by offsets, but numbered with counting numbers, that is, starting at 1.

Actually, the copyrights for Star Control 1 and 2 remain with the original developers, and Stardock has acknowledged that and is trying to work them for the new game. Or at least, that's what Brad Wardell, the CEO of Stardock, posted on the boards for the open source Star Control 2 game.

Apparently, Stardock has contacted the authors of Star Control 1 and 2 and is discussion with them on the new Star Control game. The linked post is from Brad Wardell, Stardock's CEO. Stardock been interested in doing a sequel to Star Control 2 for a while.

That's ridiculous. How can you possibly know what a machine intelligence capable of destroying humanity is going to look like? We're nowhere near the algorithms that could produce that type of intelligence.

Maybe it's a dumb algorithm simply caught in a self-replication loop. Maybe you'll never see two robots arguing over "white" or "black", because there's only one single "intelligence" spread over the internet - that seems more likely with the rise of cloud computing.

There may be plenty of reasons to dismiss this type of institution, but "human intelligence doesn't work that way, so machine intelligence won't either" isn't one of them.

Contacting the earlier developers is good advice. Unfortunately the OP doesn't say how much code there is. Understanding 10K lines by reading the source code is feasible; doing so for 1M lines isn't. Documentation is of some use, but it's typically scant and years out of date. Really, the best guide is an explanation given by someone who already knows the codebase. A good way to proceed here is to spend a bit of time digging around the codebase by yourself, write up a proposal for some significant improvement, and send it to folks who were active when the project was up and running. With a bit of luck they'll reply with criticism and suggestions for improvement.

Yes and
Make a copy!

Find a good editor or development tool, build tag files and start reading. As you drill down annotate the code with XXX-your-initials-B:, XXX-your-initials-Q: and XXX-your-initials-A: (your bugs, questions and answers)...enhancement too.

Write tests to validate what you know... or think you know.

Consider adding "asserts()" if there are known but un-diagnosed bugs.

Old school would be print it out, add thumb tabs, mark it up and build a flow diagram. Old green bar computer paper is still available as are the handy hand tools for making flow diagrams. The size of the paper is about right... Binders for green bar paper can still be had...

Google and quickly read articles on "Literate" programming. There are many tools... One of which is Doxygen http://www.stack.nl/~dimitri/doxygen/

This is foolish arrogance. In my thirty years in this profession I have worked with many people who thought their code was 'self documenting'; all of them were wrong, and faced with their own code two years later I doubt any of them could immediately follow it.

I claim my code is Self Documenting, and I can absolutely & immediately catch the past train of thoughts by following tracks of code lain down even a decade ago or longer. Not that I'm saying you're foolish or arrogant yourself (although this may be the case), it's just that what you call 'self documenting code' I call 'self commenting code' -- There is a subtle but significant difference.

I never liked the term 'self documenting code' meaning expressions that describe themselves implicitly. I always thought 'self documenting code' would be better defined as code with good descriptive comments along with the reasonable symbol names. I consider my comments part of the code when I say that my code is self documenting. I use descriptive doc-comments, as well as code-comments and generate documentation from the code itself with Doxygen. My source code editor understands the comments. When I hover over or [context-key] while on an occurrence of a variable, function, structure, etc I'm shown the remarks for that symbol or its type. This helps considerably increase my productivity; Eg: The order of method parameters and descriptions of data fields can be accessed immediately as I type rather than requiring me research external documentation. Thus, taking the time to write good documentation within the code itself actually pays off by allowing me to write more code faster. Since my source code files are sufficient input for the generation of a fully descriptive HTML (or LaTex, PDF, etc) documentation I assert that my sources are 'self documenting code'. As for merely using symbol names that comment on their purpose: I call this 'self commenting code' instead.

For my fist games I used ANSI / ASCII art necessarily for "graphics", so naturally I insist my source code editor include line drawing and texel raster tools at the very least in order to make self illustrating comments. It's too bad the text based image formats (like SVG) are so damn verbose, and code editors don't display such as graphics within the source. Addressing this and adding graphical features to my source code editor is on my //TODO list; Now, that would be truly Self Documenting.

So much to do, so little time.

You weren't very good at SC2 then. I am out of practice now, but back then I could beat almost any ship with any other ship, including taking out a Chmmr Avatar with a Pkunk Fury.

While this is true on average, there has been some relatively interesting results lately. The Star Control 2 port named Urquan Masters added internet multiplayer for melee a while back. The result is their forums are full of some interesting ship rankings on which is best. There have even been some pretty good results of redoing the cost of each ship based on how powerful they actually are. Results are pretty surprising.

http://forum.uqm.stack.nl/index.php?topic=3816.0

Just one example of many. This particular one is geared toward veteran arena players, however.

How do you write code to do PR/create docs? Please, be my hero.

Docs:
Doxygen

PR: /. etc

Hey, you could name your Windows servers Druuge names. That would only be fitting.

An Hadoop cluster could be given spathi names.

On second thought, I know waaay too much about UQM.

Hey, you could name your Windows servers Druuge names. That would only be fitting.

An Hadoop cluster could be given spathi names.

On second thought, I know waaay too much about UQM.

What about using doxygen

Ohh, I think we already know what that would look like.

The wasted space isn't the only problem. What's worse (and far, far worse IMHO) is the way the keyboard is laid out. The 3rd row down is placed too far to the left - the A and Q almost line up. Caps-Lock is WAY too short, and enter is too wide. Bit of the inverse of the crap Apple once pulled off. To add insult to injury, the >, <, ? and " keys have a different size.

Really, I'd run away from that keyboard FAST.

Doxygen is my favorite tool for C/C++/Java programming. It also handles some other random languages as well. Its main purpose is to create documentation (think javadoc but Open Source, handles more than just java, and better results). Here's an example of what it can do.

Anyways, related to your post, doxygen can map out the call graph from functions and dependency/include graphs of files. It may be helpful in understanding the structure.

May I recommend doxygen for your documenting needs. Does what javadoc can do + more (can create 'call graphs', works on several languages, and outputs to html, pdf, manpages, rtf etc etc). It is truly an impressive piece of software.

Yes - I have used doxygen for both C and C++ code. When using the full-source option it can be quite slow, but in conjunction with the "dot" tool it produces quite nice call graphs.

See http://www.stack.nl/~dimitri/doxygen/diagrams.html for info.

http://www-scf.usc.edu/~peterchd/doxygen/example/main_8c.html (to pick a random example found on google) has an example of a doxygen-produced page giving both an include-file graph (at the top) and a call graph (at the bottom).

As you can see it gives a quite nice at-a-glance overview of the program's structure. It will happily produce individual pages for each function in your program showing a graph of functions that call into it and all of the functions it calls.

Note that the boxes in the diagrams are hyperlinked to the corresponding page for that function/header-file.

See:
http://www.stack.nl/~dimitri/doxygen/
and:
http://uml.sourceforge.net/index.php

These tools allow you to 'visualize' a codebase in several very helpful ways.
One important way is to generate connection graphs of all functions.
These images can look like a mess, or a huge rail yard with hundreds of connections.
The modules, libraries, or source files that are a real jumble of crossconnected lines are a clear indication of where to start clean up activities. :)

Good luck!

For C++ code, Doxygen can be useful, as it shows the class inheritance. As requested, it uses a (rudimentary) parser. It works with several other languages too, although I can't vouch for its utility for them.

My goal is to be able to extract all of my documentation from the source code. This keeps the version control simple - since you don't have to syncronize 10 documents as changes are made. There are various tools for doing this depending on your language of choice.

Perl has perldoc functionality built in - limited in some respects. Python has doc strings - but needs more processing to generate readable documentation beyond API lists. A more general purpose tool for generating documentation from source code is doxygen - currently supporting C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D. There may be other tools that I am not aware of.

Keep it simple.

For a source browser, doxygen[1] is a no brainer. Turn off Latex, turn on recursive and static members, tell it to include code, tell it to link functions, and tell it to go to town.

VI is pretty powerful (but less intuitive) if you use ctags on your source. I personally prefer doxygen, but tags work well.

People think of it as just a cross language javadoc, but your code doesn't need to be documented to use it well.

                        --Michael

[1] http://www.stack.nl/~dimitri/doxygen/

Aw, damn! I was just playing a session of the Ur-Quan masters, so you beat me to posting it!

Also, to anybody who doesn't get the joke...
http://uqm.stack.nl/wiki/Peace_Vaults

I've found Doxygen to be pretty handy, it'll output to a bunch of HTML files and even create nifty relationship graphs for OO languages like C++

http://www.stack.nl/~dimitri/doxygen/

If you're looking more for documentation of existing code, doxygen is great. It produces click-to-follow hierarchies, graphical pictures of trees, and can will intelligently display some of the comments it encounters. It can produce output in html, LaTeX, rtf, PS, PDF, and even man pages. And I know from experience that it can handle some pretty massive projects.

Pick your color Korh-Ah or Kzer-Za

"Well, I guess a lot can happen to a species in three Drahn like turning green and evil."

Pick your color Korh-Ah or Kzer-Za

"Well, I guess a lot can happen to a species in three Drahn like turning green and evil."

I probably blew most of my sophomore and junior years of high school on Star Control II. Even now I'll play through the whole thing.

Maybe you know, maybe you don't: Fred Ford and Paul Reiche III released the source a few years back, and it's being updated for modern systems as a open source project. Since Accolade / Infogrames / Atari / whoever-buys-them-next owns the trademark to "Star Control", it is now called "The Ur-Quan Masters". The project just released version 0.5 at the beginning of February, which you can find it on their sourceforge site. The project incorporates both the DOS version and the 3DO version -- so you can choose your music, spoken voice vs text, etc. Very nicely done.

I had a MythTV box for about two years and it did it's job wonderfully. The only problem I had is that I really don't watch that much TV, and MythTV rewuired me to pretty much dedciate an entire system to that task. I finally found a better solution for my needs, and that's just vcr and TVTime. I use TV Time to watch live TV, and VCR + mplayer to watch prerecorded shows. There's a web frontend for VCR, but I don't use it, it's just easier for me to set up cronjobs. So if you're not looking for an HTPC but rather just adding HT capabilities to your main system, I'd suggest a set up like this. There when you need it, out of the way when you don't. No extra processes or services that need to be running.

Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.

No Perl? :(

It would be great to see Python get some better documentation tools

Doxygen claims to support Python.

Now fully mirrored:
http://www.stack.nl/~vexocide/xbox360.html
Incl. all the pics

One word.. doxygen. I had been working on a program by myself for a few years and was really the only one who knew the guts of it. We got a new person on it so I could move on to other things, and rather than spending a week or two showing her what she needed to know, I spent a few days adding doxygen comments to the project, and she was able to read the generated documentation for herself and picked it up in no time. It plugs in to Visual Studio very nicely if you use that, and if not, you can easily write a batch file to update your documentation. I just can't say enough good things about this tool. If you can get your developers in the habit of documenting in the doxygen format, your documentation will basically write itself.

Segfault

OK, I'll bite. Mycon Overloads...http://uqm.stack.nl/wiki/Mycon/

Now, if only we could figure out how to speed up light, everything would be great.

Doxygen is a good tool for many languages. It works best for C++, but it also has some limited support for PHP, which is in your list of requirements. There is also a fork of Doxygen called DoxyS. It generates prettier output for C++ but may not support the other languages as well as Doxygen. Another tool inspired by Javadoc is PHPDoc for PHP code. However, it does not seem to be actively developed anymore.

For plain C code, I prefer gtk-doc, which generates better output than Doxygen (IMHO, and for C only). You can see an example of the gtk-doc output by browsing the GTK+ API documentation.

Since you also mention Visual Basic, you could have a look at VBDOX. I haven't tried it myself so I don't know if it works well. There are some screenshots on their site, so maybe you should have a look and decide if you like the results.

Other than that, there's the Commentator...

You still need to know how to write good comments but I find using doxygen is a great tool for generating useful documentation directly from comments in your code. If you haven't heard of it give it a shot.

http://www.stack.nl/~dimitri/doxygen/ Doxygen homepage.

You do mess with your air flow this way. and it is shit ugly. the two bolts that is.
It appears that people and manufacturers are not taking a proper air flow into consideration anymore. standard pc's are now riddled with fans blowing in all directions.
People should take a lesson from the sun E450 type machines for instance. although they are huge beasts, the air flows from front to back, is guided neatly past all 4 processors (which do not have fans of themselves) and passes out the (3) powersupplies.
Temperatures can be monitored from inlet to cpus to PSU's like this , and there is nothing obstructing the air flow. ever. excellent design.
Apple does the same in their powermacs, but this man either forgot or thought 200W (100W per proc) would be easy to dissipate.

The "auxiliary documentation" that is mentioned at the article being kept up-to-date and reflecting code changes is now implemented as javadoc and its competing technologies like Doxygen or phpDocumentor.

• You want to save money at the expense of ease of use for customers and you are already invested in pdfs.
• You want to provide a big document that can be downloaded and printed off all at once (I never want this out of online documentation).
• You need to have everything look the same everywhere.

The answer depends on how secure your passphrase needs to be. Start with a normal phrase and then with a bit of random help, distort it. Make a nonsense phrase by changing words. Remember to switch the sentence structure around in a random fashion. Add a few random words or characters to enhance the security. The goal is to create something you can remember and last as long as a brute force attack on the IDEA key.

The phrase, "my unbreakable super pass phrase can't be beat", is weak by itself. So what if we change it some? "mile unbraking stupor past froze can tent bee beets" is all well and good except that in an attack, a homophone dictionary may be used. On the other hand, in one pass we have a nonsense phrase that has a different structure and words that don't quite logically connect. Add several random characters to make it impossible to guess by any means other than brute force and you are done. The phrase is fairly easy to remember because you used a normal phrase to construct it. If you forget the actual phrase you will probably be able to reconstruct it. Being human, we tend to do things the same in a predictable manner.

For more security, you can generate fully random phrases or character sequences. This will take time and may be difficult to remember. Your level of security is easy to control by limiting the key length. One nearly foolproof method is Diceware

You should read about XP (extreme programming)...

I have. And way back into last century even. :-)

You're right that the initial idea is always different after seeing prototypes. But for this exact reason you shouldn't document your code. Code should be disposable, so don't waste time writing other than what the computer needs.

And this is where I'll have to strongly disagree with you. Even "Extreme Programming Installed" (a book I personally belive wonders off a bit from Beck's best XP) says to use UML.

Additionally, some of what I've seen in the best projects is the use of good Javadoc, DOC++, Doxygen or some such comments. The best time to write those is while the design is fresh in people's minds, such as in writing up initial tests or first writing each class. Additionally, it's much easier to keep up to date, and helps greatly as people need to go in and refactor code. Oh, and Eclipse has good Javadoc support, and having Javadoc comments helps it work even better.

Of course, I've gone Extreme myself on different projects by writing Docs in XML. Just poke a single XML with different XSLT stylesheets and get end-user API documentation, internal implementor guide documentation, and full test case source code all from that single sparse XML source. (But especially with all the workflow benefits one gets in Eclipse from having proper Javadoc comments around, those are well more that "disposable").

Doxygen does exactly what you described. See item #2 in the link.

If that doesn't work look up programs that will convert to UML. Since you didn't mention it in your question I'll expand: Unified Modeling Language diagrams are a standardized means of describing the relationships between objects in classes. To any Slashdotters out there in college looking to take a software engineering course, you'll be seeing a lot of UML.