Slashdot Mirror

Whatever you start off with, give it a run through doxygen first. Esp. with C++, this will save you a lot of time looking up definitions of objects and other stuff buried in various (and overridden) header files.

Enterprise Architect is very nice, since you can do forward and reverse software engineering with it.

However, if you do not have the budget allocated for it, a good compromise is StarUML,
which became very nice and usable lately and has the same "feeling" and menu-driven approach
like the old Rational Rose and Enterprise Architect:

http://staruml.sourceforge.net/

http://sourceforge.net/projects/staruml/files/staruml/5.0/staruml-5.0-with-cm.exe/download

As for Rational Rose, the first original version was very good with some known quirks until it
became IBM Rational Rose and was converted into a "super Eclipse" plug-in.

So, if you enjoyed drawing UML diagrams in the old Rational Rose,
then Enterprise Architect and StarUML are the tools that you are looking for.

And if you do not like to draw with a mouse then Graphviz Dot and a good text editor is for you:
http://www.graphviz.org/Download.php

For tracking issues / documents and schedule,
I can recommend either BugZilla, Mantis or BaseCamp:

http://www.bugzilla.org/download/

http://www.mantisbt.org/

http://basecamphq.com/

As for the actual writing part, your company should already have a good set of Word Templates,
to document the actual Sofware Requirement and Specification (SRS), Sofware Design Document (SDD),
Change Request Document (CRD).

Once, you got those set up, then we mostly use MantisBT or BaseCamp to share, comment and track them.

As for producing code documentation, the choice are: Doxygen, JavaDoc, NDoc, JsDoc:

http://www.doxygen.org/

http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html

http://ndoc.sourceforge.net/

Or just use Doxygen--the comments ARE the documentation.
In a good way, that is: The docs are generated from the comments.

A lot of times a programmer is stuck without those tools for any number of reasons. A lot of times people are stuck with spaghetti code which there is no documentation or design pattern to work with. I think your answer is assuming that the planets are aligned and we live in a utopia. Do you have any suggestions for people who have to deal with reality?

Doxygen. With the proliferation of open source projects, "no tools" is no longer a valid excuse.

Now, I'm not saying that doxygen is going to be able to unravel all his code for him, but it's a good start, and it's free. It may not help much if there's absolutely no structure (a 5,000 line main(), for example) but most code isn't quite that bad.

If his boss doesn't approve of that one in particular, this wikipedia article has many others to choose from.

And finally if his boss says, "No, you're supposed to be a whiz kid, you figure it out with the tools I gave you," the correct answer is to raise one finger in salute and find a job without a batshit-crazy manager.

How about Doxygen; see their site? Gives you the whole OO inheritance structure, lists of function caller/callees (if desired), graphical representations, etc, etc. And it lets you browse through the code with a web browser...

• Class constants must be string literals and only string literals (no variables, arrays or objects).
• Type-hinting is confined to arrays and objects (feature?).

Doxygen. Combined with KDevelop or similar IDE, it produces quite good API docs.

In my first job, years ago, I learned that developers will not usually keep any external documentation (e.g. some document-only file other than foo.c, whether troff, LaTeX, or MS-Word) current, but those same developers will usually keep internal documentation (e.g. documentation embedded inside foo.c or foo.cc) current. Back in those days, we were using a DEC VAX 11/750 and the embedded documentation used troff markup, but similar and more modern tools are available today for a wide range of platforms.

So folks should consider using open-source tools like HeaderDoc or Doxygen or (in the case of Java) JavaDoc to embed the software documentation inside the actual source files.

Mind, this is not a substitute for good coding or good documentation or good software enginering practices, rather this is a tool to help people write good code, have good documentation, and follow good software engineering practices. :-)

I'd start buy actually reading the source - building it if you can. Run profilers on it and try to get some kind of visual representation of the underlying code tree. If you have source, try using something like DOXYGEN to autogen some documentation (and structure) out of it. Someone mentioned Rational - you can get a trial license. Try to understand what the code does. For the most part games are straight forward, in that you have objects that have specific behaviours. You can try to establish the object hierarchies and see if you can redefine these to make more sense - or just be different.

For the fragments of source you don't have - try using tools such as truss to track flow of what is going on. GDB is your friend and you probably want to try running it through the debugger - especially if the extracts you were given were compiled without stripping the symbols. nm is also another useful one at trying to get an idea of the symbols in your binary and establishing 'from meaningful names' what on earth goes on inside.

Push your binaries through a disassembler like ldasm or datarescue - win. NASM also has a disassembler. Try and get a feel for what is going on.

Now comes the hardpart - it's not called reverse 'engineering' for nothing. You've done the reverse bit. It's now time to engineer a solution which shows that you've gone through the 'reverse' bit. It can be y our view on how the code should work. Don't be affraid to reuse resource files/bitmaps, etc. That's allowed. It's the code which counts. You'll probably find that the assignment gave you something which was sub-optimal, in either design or processing - or both. It's your turn to write it the way which it should have been written. I'll leave the 'team dynamic' to you. Don't let one person have all the fun. Probably you - it's good to give others a chance. See what people are intersted in and allocate the work load. Just be prepared to fix everyone's bugs the night before submission - it's not so bad - it's 'fun.'

It sounds like you are unable to build the complete system and run it, since you're missing functionality. This removes the possibility of using runtime tracing tools.

The first thing I would do is run something like Doxygen over it to generate a cross-referenced description of the structures. It won't give you a global view of things, but it will give you a decent browsable view of the code itself. Another response mentioned GNU GLOBAL which may work better for you. Yet another possibility is LXR, though it may not work as well in C++. Regardless, a nice thing about Doxygen is that, when used with GraphViz, you can get useful diagrams generated showing class containment and file inclusion graphs.

After you have that, get out your paper and pencil, and start drawing and manually tracing things. That's how I go about coming up to speed on new code I can't execute and step through. Eventually transfer that knowledge into a text file (or, nowadays, a wiki) so that others can benefit from it.

http://www.doxygen.org/ is great.

I just wrote a piece of code and commented it properly. I used Doxygen style comments.
The beautiful output documentation produced by Doxygen automatically was worth the little extra time spent on commenting my code.

Totally agree with parent.
Ultimately, the code is the design.
To me, a properly documented header/source file speaks just as clearly as a UML diagram -- and it remains in sync with what the code is today.
So I like to use doc-from-source generation tools such as doxygenhttp://www.doxygen.org/ or javadoc.

The design document should not include any information that is readily available in the code.
Instead, it should provide:
- the big picture, illustrations, an introduction to a module's architecture, and how the module fits in the system.
- an explanation and justification of all the key design choices that where made.
- cross-referencing information (i.e. traceability of requirements, etc).

I can recommend Doxygen. It allows you to intermingle API documentation and code; you put a specially, but easily formatted comment in front of or behind each thing you want to document (class, method, member, #define, etc.), and then Doxygen extracts the documentation, producing a variety of output formats (HTML, LaTeX, RTF, PDF, and others). A lot like JavaDoc, and a lot like the Qt documentation as well.

For HTML output, I'd recommend using a custom CSS stylesheet rather than the one provided, though. Fortunately, everything is CSS-enabled, so it's easy to change the look 'n feel.

• C++
  • jEdit is a Java programmer's editor with excellent C++ support. I do development on Linux, Win32 and MacOS X, so it's very nice for me to have one editor I use on every platform. jEdit's not as featureful as, say, Emacs, but it's considerably more friendly to use.
  • Boost. If you're writing C++ and you're not using Boost, you're committing a crime against yourself.
  • Python. With Boost's Python library, it's easy to make your C++ applications scriptable. Write the heavy lifting parts in C++, then make those parts callable from Python. Do the rest of your development in a far safer, more sane language. You get almost all of the speed of C++, and far fewer headaches.
  • SWIG is another tool that's excellent for creating scriptable C++ applications.
  • Subversion for your version-control needs. Nothing else will do.
  • Doxygen for all your documentation needs. Learn it, love it. Your code's not done until every public part of the API has been doxygenated.
  • The GNU Autotools are really, really awful. They're also far better supported than Scons or pick-your-Autotools-replacement. Get ready to feel the pain of m4 macros. Sorry. :(
  • The GNU Compiler Collection started getting a good C++ compiler around version 3.0. I've been quite favorably impressed with 3.3, and I'm looking forward to 4.0. I don't recommend it for Windows, but for Solaris and x86 Linux it's beautiful.
  • I haven't found a good C++ unit testing framework yet. If you find one, please let me know.
• Java
  • Eclipse is an excellent Java IDE. jEdit also fits the bill nicely, if all you want is an editor. I use both frequently, and am quite pleased with both.
  • Subversion again for your version-control needs.
  • jUnit for unit tests. Your code's incomplete unless you've written unit tests for it.
  • Javadoc for documentation. I would recommend Doxygen, but it's quite possible you'll be deploying your applications on machines that don't have it installed.
  • Ant for all your build needs.

• C++
  • jEdit is a Java programmer's editor with excellent C++ support. I do development on Linux, Win32 and MacOS X, so it's very nice for me to have one editor I use on every platform. jEdit's not as featureful as, say, Emacs, but it's considerably more friendly to use.
  • Boost. If you're writing C++ and you're not using Boost, you're committing a crime against yourself.
  • Python. With Boost's Python library, it's easy to make your C++ applications scriptable. Write the heavy lifting parts in C++, then make those parts callable from Python. Do the rest of your development in a far safer, more sane language. You get almost all of the speed of C++, and far fewer headaches.
  • SWIG is another tool that's excellent for creating scriptable C++ applications.
  • Subversion for your version-control needs. Nothing else will do.
  • Doxygen for all your documentation needs. Learn it, love it. Your code's not done until every public part of the API has been doxygenated.
  • The GNU Autotools are really, really awful. They're also far better supported than Scons or pick-your-Autotools-replacement. Get ready to feel the pain of m4 macros. Sorry. :(
  • The GNU Compiler Collection started getting a good C++ compiler around version 3.0. I've been quite favorably impressed with 3.3, and I'm looking forward to 4.0. I don't recommend it for Windows, but for Solaris and x86 Linux it's beautiful.
  • I haven't found a good C++ unit testing framework yet. If you find one, please let me know.
• Java
  • Eclipse is an excellent Java IDE. jEdit also fits the bill nicely, if all you want is an editor. I use both frequently, and am quite pleased with both.
  • Subversion again for your version-control needs.
  • jUnit for unit tests. Your code's incomplete unless you've written unit tests for it.
  • Javadoc for documentation. I would recommend Doxygen, but it's quite possible you'll be deploying your applications on machines that don't have it installed.
  • Ant for all your build needs.

For all non-Java development, unless mandated by a contract, I use GNU Emacs as my primary environment, with the GCC tool chain and GNU Make. This works amazingly well on all stages of development, but as others have said, keep things simple: try to avoid mazes of recursive makefiles, for example (read Peter Miller's Recursive Make Considered Harmful, then read it again.)

Your choice of tools will depend a bit on how cross-platform you need things to be. If you are developing now, or think you will be developing in the future, for multiple platforms and compilers, take that into account from the start and save yourself a lot of headache. Don't bother with AutoGen and friends unless you are distributing this to third parties: it's a PITA. It's great if you have absolutely no control over future systems, but otherwise there are better ways.

For Java development Eclipse is going to be your very good friend. I'm not a big fan of IDEs, but Eclipse is really nice insofar as it integrates with the Java language very well and can help you a lot. It's refactoring capabilities are worth the learning curve. Unfortunately I have not had a lot of luck getting ANT integration working, so I maintain a separate ant build file that I use for release builds in my projects.

For documentation purposes Doxygen is the thing to use. It has Emacs integration as well (written by yours truly). We use this to generate reference documentation, and then have Python scripts to massage the HTML output as we need. With its XML output you can use XSLT instead, though I haven't tried that. We need to produce multilingual documentation, and after many different attempts with tools have settled on LaTeX with a customized version of the Python macros. It works really well, if you can find doc writers who are comfortable writing with it. We are experimenting with Lyx to see how it integrates with our hand-coded documents. We use JavaDoc for Java reference documentation, though we could (should) migrate to Doxygen.

Other tools that are essential: Valgrind is a must use. I prefer it to Purify. Use Bugzilla for bug tracking: easy to set up and maintain. I recommend Perforce for your SCM. I'd avoid CVS. Give Subversion a look, but we've been happy with Perforce. Depends on how much you want to spend. We use AutoGen a lot to generate sources: very useful. And pick a scripting language you are all comfortable with and use it: Python is what we use, Perl works. It doesn't matter which one you use, as long as you're all comfortable with it. We have Python scripts that produce hourly summaries of Perforce activity, for example. We've tied our Bugzilla into Perforce... lots of things can be done.

Use DoxyGen!

It supports multiple languages, so it's a more generic approach to automated software documentation..

I'm not talking about a manual for your product, I'm talking about keeping track of what you do, what your staff does and what the results are. It may be laborious to do so, but there will be times that you'll be glad you did. Also, you may wonder why something was done a certain way a few years ago; having some kind of knowledge base written down will be invaluable.

Document the code. Make sure that people adopt javadoc-type conventions. Check out Doxygen if you're not doing Java development, and make it a policy that people need to comment their code in places that are not painfully obvious. Programmers can be quite fat headed at times about this, because "hey, I know this, and if you can't read this then you aren't good" or whatever. What is obvious to them might not be obvious to others, and if you want to do a quick scan over some code, its easier to read a comment defining a block than figuring out their "spark of genius du jour" (sometimes people write things overly clever thinking that its more efficient when in reality its not and only making things harder to maintain).

The point of this is that:

1. Your staff will not be the same forever; people move to other projects or other jobs.
2. You will forget details.
3. You will find it difficult to recall exactly what you and your staff did several months ago, especially if the project is large and fast moving.

By keeping documentation, you will always be able to back up, defend, promote and prove (or disprove) your ability to manage. Now you just need to make sure you make the right decisions; nothing can help that except experience and good judgment.

I'll occasionally diagram ideas when thinking about how to implement something or design an API, or sometimes in documentation. Dia has some nice looking boxes in a category called "UML" which I use sometimes. Also, Doxygen can generate collaboration diagrams that look like UML diagrams. Mainly I just need some boxes and arrows. All that other stuff is not that useful.

Maybe it's useful to autogenerate IDL or someting, but I've always found that to be a completely broken concept entirely.

Reed

As far as I know, the more useful tools out there do things like restructure your written code for readability or automagically generate documentation from specially formatted comments.

Granted, I haven't checked on what other automagic source massagers do in a while, but I would imagine that there are none that do what you're describing to the point of being actually useful. What's useful falls into a few basic categories, namely WHY did this get written, and WHO do I blame for this crap, anyway. the first being generally more useful than the second, unless you're playing the cover-your-ass game. Most modern IDE's will try to fill in the second for you in header blocks or string definition files, but considering how hard it can be to go back to uncommented code a few weeks later and figure out what the hell you were thinking, I seriously doubt that anyone's got software that allows the computer to figure that out for you.

Just my .013 Euro...

Unfortunately graph generation is pretty slow, but otherwise it's a fantastic tool.

Doxygen is a good choice for C++, C, Java, Objective-C, IDL... I used it to get into a ~50K line project a few years ago and have used it regularly whenever I'm forced to use C++... Get Graphviz as well so Doxygen can draw pretty pictures for you.

Doxygen http://www.doxygen.org tags can be used to do lists on TODO since 1997. A nice example can is http://www.stack.nl/~dimitri/doxygen/lists.html

I tried Dia some time ago and found it very frustating to use, with most of built in objects being too restrictive and lacking enough variety of connection points to terminate lines and arrows.

For line diagrams (e.g. for documenting 3D graphics algorithms), I've moved on to qcad, which is a 2D CAD package.

For OO design, you can try doing this backwards : prototype the interfaces and classes and run doxygen (with dot) to generate inheritance and collaboration diagrams or XML output for post-processing. This probably fits in more with an extreme programming prototype/refactor style methodology than a complete up-front design methodology.

For state diagrams, I've had some success using dot on its own.

Using doxygen and dot has the significant additional feature that the files you edit are all plain-text files, so you can use your existing source revision control system (e.g. CVS)

Even with these packages however, I usually still find a pen and paper (or a white-board or blackboard if available) the easiest and fastest option for sketching out an initial design, or during discussions of various design alternatives with colleagues.

Adequate documentation of code isn't just a problem for open source projects - pretty much everywhere I've worked the documentation tends to be poor unless there is a strong contractual obligation otherwise.

If the documentation is for people contributing code to the project, Doxygen is great for generating documentation from your source code, which you can annotate with javadoc-style comments. Great for seeing how convoluted your inheritance trees are becoming.

If the documentation is for people who use the project, but aren't coders, then I'm a bit more stuck. Basing it around a markup language like HTML or LaTeX would make it easiest to convert into whatever document formats people require, and if it's in HTML you can just publish it on the web for lazy people like me who don't want to download the whole docs.

Matt

You could do the same with C/C++ using Doxygen, a free tool that implements Javadoc style documentation for C.

Get it.

I wish it supported python, which is the other OO language I routinely use.

Doxygen lets you mark up your source code pretty easily, and generates decent looking documents. You can use the same markup (and cross-reference facilities) in non-code documents processed at the same time.

> See above. Kdevelop also makes it easy to set up
> automake/autoconf build methods, even for people
> who aren't familiar with them.

Those people have no business doing software development.

There are lots of things in the world of software development. Lots of languages, lots of miscellaneous helper tools. Lots of IDEs. I've never used automake/autoconf in my development career, and I've never needed to. Hard as it may be for you to believe, autoconf/automake familiarity is neither necessary nor sufficient to be a good software developer, in C++ or any other language.

I also reckon that you believe WYSIWYG "html editors" have a place? Maybe for my 10 year old female cousin, but not for anyone else. Yet again, they shouldn't play the game if they are afraid of the ball.

Personally, I actually do think that WYSIWYG "HTML editors" have a place. I also think applications like Lyx have a place. It's just a shame that at the moment there aren't any standout contenders in the HTML side that focus on generating standards-compliant HTML (at least as far as I know, I'd be happy to be corrected on this point).

As an aside, is there any particular reason you say "my 10 year old female cousin," rather than just "my 10 year old cousin" or "a 10 year old child"? Are you trying to imply that she's doubly disadvantaged in being ten years old and female? Or perhaps even more disadvantaged in that she's your cousin?

SQL is a backend issue, there are no reasons for it to be tied into a toolkit.. if so, it is the worst form of bloat.

Hard as this (again) may be for you to believe, but Qt is not just a GUI toolkit. GUI stuff is a large part of it, but not the only part. I mentioned in another comment that I know of one app, Doxygen, that used Qt without using any of the GUI stuff - simply because the author really like the fact that it abstracted the low-level platform-specific stuff so nicely.

The other major issue with QT is the terrible licensing. It still sucks, and I doubt it will ever not suck. I would never base my software on something that will make it as valuable as a pile of rubbish one day.

IDE.. hah, I'd like to see you use Kdevelop on a text terminal.

WTF are you babbling about? If you want to restrict yourself to using a text environment, do so. Nothing stopping you. Of course, if you're supposed to be developing a GUI application, you might not be able to test it at all, but I'm sure that doesn't matter for someone like you.

Have a nickle, get yourself a real computer.

Pete.

I was examining cross platform GUIs a couple years ago, and gave wxWindows a try; it's ugly (full of arbitrary little macros)

and, as the subject says, when I installed it and tried their example programs, some either failed to compile (or more likely) failed to work (my memory is unclear).

Overall my impression was that it was a mess. Now, that was 2 or more years ago, but I haven't heard much about wxWindows since.

We went with Qt, and it's clean and fast; I prefer it even to MFC (which admittedly may not be saying much).

I certainly wouldn't recommend you change from Qt to wxWindows... I do think Qt is technically superior to wx, but there are reasons why you might find wx more appropriate for future projects with different needs. Try installing wxPython and have a look through the demo app - I find this a great way of showing off the features/functionality/look/feel of wxWindows to people, even if all the demo apps are written in Python. You can get a good feel for the way the same apps would look in C++ even if you don't know much about Python.

Pete.

In the C/C++ world Doxygen is getting a lot of attention as a standard documentation tool.

Anyways, like another poster has said, look around: that's the great thing about Free Software. Check out what KDE does (I think they use DocBook, but don't quote me). Check out how the GNOME guys keep themselves on the same page (no pun intended). It's all transparent and readily available for you to check out.

Ryan T. Sammartino

Apart from the name, this is the best tool I found for C++ / IDL / C. Better than Javadoc!
www.doxygen.org

That's the best way to do static documents of large size, in my opinion. Tutorials and books on the web, that sort of thing.

If you use a system such as doxygen to automatically generate documentation from code, then LaTeX is nice as an intermediate output because you can make a web page as well as nice printed output.

So I aggree with you that browsers should not be interpreting or compiling LaTeX; that doesn't mean that you have to refrain from using it when it might happen to be the best tool, however, just translate the LaTeX to HTML when you are done.