Using table-of-contents in code?

Do you use table-of-contents for listing all the functions (and maybe variables) of a class in the beginning of big source code file? I know that alternative to that kind of listing would be to split up big files into smaller classes/files, so that their class declaration would be self-explanatory enough.. but some complex tasks require a lot of code. I'm not sure is it really worth it spending your time subdividing implementation into multiple of files? Or is it ok to create an index-listing additionally to the class/interface declaration?

EDIT:

To better illustrate how I use table-of-contents this is an example from my hobby project. It's actually not listing functions, but code blocks inside a function.. but you can probably get the idea anyway..

/*
CONTENTS

Order_mouse_from_to_points
Lines_intersecting_with_upper_point
Lines_intersecting_with_both_points
Lines_not_intersecting
Lines_intersecting_bottom_points
Update_intersection_range_indices
    Rough_method
    Normal_method
        First_selected_item
        Last_selected_item
        Other_selected_item

*/


void SelectionManager::FindSelection()
{

    // Order_mouse_from_to_points
    ...
    // Lines_intersecting_with_upper_point
    ...

    // Lines_intersecting_with_both_points
    ...

    // Lines_not_intersecting
    ...

    // Lines_intersecting_bottom_points
    ...

    // Update_intersection_range_indices
    for(...开发者_运维问答)
    {
        // Rough_method
        ....

        // Normal_method
        if(...)
        {
            // First_selected_item
            ...

            // Last_selected_item
            ...

            // Other_selected_item
            ...
        }


    }

}

Notice that index-items don't have spaces. Because of this I can click on one them and press F4 to jump to the item-usage, and F2 to jump back (simple visual studio find-next/prevous-shortcuts).

EDIT:

Another alternative solution to this indexing is using collapsed c# regions. You can configure visual studio to show only region names and hide all the code. Of course keyboard support for that source code navigation is pretty cumbersome...

I know that alternative to that kind of listing would be to split up big files into smaller classes/files, so that their class declaration would be self-explanatory enough.

Correct.

but some complex tasks require a lot of code

Incorrect. While a "lot" of code be required, long runs of code (over 25 lines) are a really bad idea.

actually not listing functions, but code blocks inside a function

Worse. A function that needs a table of contents must be decomposed into smaller functions.

I'm not sure is it really worth it spending your time subdividing implementation into multiple of files?

It is absolutely mandatory that you split things into smaller files. The folks that maintain, adapt and reuse your code need all the help they can get.

is it ok to create an index-listing additionally to the class/interface declaration?

No.

If you have to resort to this kind of trick, it's too big.

Also, many languages have tools to generate API docs from the code. Java, Python, C, C++ have documentation tools. Even with Javadoc, epydoc or Doxygen you still have to design things so that they are broken into intellectually manageable pieces.

1. Make things simpler.

2. Use a tool to create an index.

If you create a big index you'll have to maintain it as you change your code. Most modern IDEs create list of class members anyway. it seems like a waste of time to create such index.

I would never ever do this sort of busy-work in my code. The most I would do manually is insert a few lines at the top of the file/class explaining what this module did and how it is intended to be used.

If a list of methods and their interfaces would be useful, I generate them automatically, through a tool such as Doxygen.

I've done things like this. Not whole tables of contents, but a similar principle -- just ad-hoc links between comments and the exact piece of code in question. Also to link pieces of code that make the same simplifying assumptions that I suspect may need fixing up later.

You can use Visual Studio's task list to get a listing of certain types of comment. The format of the comments can be configured in Tools|Options, Environment\Task List. This isn't something I ended up using myself but it looks like it might help with navigating the code if you use this system a lot.

If you can split your method like that, you should probably write more methods. After this is done, you can use an IDE to give you the static call stack from the initial method.

EDIT: You can use Eclipse's 'Show Call Hierarchy' feature while programming.