Sign in to follow this  
X Abstract X

So I Was Thinking...

Recommended Posts

When I'm working on a personal project, often times I find myself opening up the source files of code I've written weeks ago and searching through it to find out what functions I've defined, what their parameters are, and what they return. Now, the thought of sifting through the old code often leaves me feeling unmotivated to get to work on my project. So I was thinking, is it a reasonable idea to write my own sort of documentation in a text file to outline the functions in each class? Does anyone practice this? Please share your opinions on this.

Share this post


Link to post
Share on other sites
Why write your own documentation if programs like doxygen do it automatically out of your code and your comments?

Edit: And since several of your other threads are specifically about Java, javadoc does the same for Java and comes straight with the JDK.

Share this post


Link to post
Share on other sites
Quote:

Why write your own documentation if programs like doxygen do it automatically out of your code and your comments?

Because while a documentation of all the functions, classes and interfaces is useful, it doesn't tell the end user anything about how to use your codebase.
Do NOT forget to document how all the code ties together. You can browse the doxygen of something like Bullet Physics all day and it wouldn't get you closer to understanding what to do. But look at the samples and documentation and you can get started very quickly.

Share this post


Link to post
Share on other sites
doxygen isn't restricted to document classes, enumeration, functions, namespaces, ... It also provides support for the todo list, example code (inclusively links into the member documentation), and logical grouping. And the \page, \section, \subsection stuff allows to incorporate plenty of explanatory pages smoothly.

Share this post


Link to post
Share on other sites
Quote:
Original post by X Abstract X
often times I find myself opening up the source files of code I've written weeks ago and searching through it to find out what functions I've defined


Generally, you should try to design your code so that you DON'T need to look into the internals of classes to know how to use them, but maybe that wasn't the issue. :)

As for simply enumerating the public parts, that's best left to your IDE (or if that's not available), a Documentation generator. It's so much easier to browse through HTML documentation than reading through multiple .hpp or .java files.

I mostly write direct in-source documentation only for classes, methods and constants, if more explanation than that is needed that should probably be put in some code design doc in first place.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this