How to refer to specific areas of code in documentation?

Question

I'm about to leave a project, and before I go my boss has asked for me to document code (I've not documented very well). It's not a big deal, the project is not terribly complex. But I'm finding places in my documentation where I would like to say, "Notice on line XYZ that such-and-such happens."

In this case, it doesn't make sense to refer to a specific line number, since adding or deleting a single line of code would immediately outdate the documentation. Is there some best-practice for referring to a specific line of code without referring to it by line number?

I've considered littering the code with comments like:

/* linetag 38FECD4F */

Where "38FECD4F" is some unique tag for that specific line. Then I can put in the documentation, "On the line tagged '38FECD4F', notice that such-and-such happens."

Any other ideas? I feel like it's generally better to document code units as a whole, rather than specific portions of them, but in the case of this particular project there are LONG swaths of procedural code, which have never been refactored into smaller units.

Answer 1

If I understand it right, you seem to have a unique problem. What you want to do it refer to a specific line of code in comments which are written in some other portion of the same code.

I don't usually come across such scenarios where I need to refer to an exect line # in some comment written elsewhere -- generally code is documented right where it is written.

I don't know of any standard way to do this -- but off the top of my head...

You can refer to portions of code via it's context -- i.e. things surrounding them.

Notice above the definition of func1() that such-and-such happens

Note that just after the for loop that iterates over recordXYZItr, that we are also calling the method gc()

Caution: In the method yahoo(), right after the declaration of variable PQ, we are also swapping the values in A and B, so the mapABC object there also needs to be copied

Another way is to add descriptive tags. Instead of something like 38FECD4F, you can say Some XYZ implementation or BUGFIX 1474, and then refer to that somewhere else.

Answer 2

It depend a lot of how the code was written, and I understand that it may induce a bunch of refactoring that you are not here to do.

But... if you need to refer to a specific line of code as a whole unit, wouldn't it mean that its some code that represent an abstract operation, and thus could be refactored in its own method/function? Once its in a method, its pretty easy, just refer to namespace.class.method Of course that mean having methods that are very small, about 5-10 lines long or even less. With Doxygen, you can put the documentation on top of the method, and it would always stay in sync with the name of the method/class/namespace.

Answer 3

I suggest you take a different approach, other than linking from some code-external documentation to code:

1. add comments to your code, using a tool like doxygen.

2. should there be a need to explain some concept in more detail than is suitable within the (newly created) code's documentation, you can always create a separate document and link to that.

This way you can easily generate the documentation as a web page or as a PDF, and it stays consistent with the code. Using some artificial tags will become very difficult to maintain and even more difficult to understand for the uninitiated.