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.

  • Are you referring to the specific locations from the enclosing methods or from the top-of-the-file-summary comments? In the latter case you can use the "#" JavaDoc style.
    – arin
    Dec 28, 2012 at 16:50
  • I've usually referred to file and method ("Notice in file ABC in method XYZ such-and-such happens") but I'm curious to see what answers come in. Dec 28, 2012 at 16:50
  • 7
    Wouldn't it be more expedient in these cases to just put the comments into the actual code? Dec 28, 2012 at 16:50
  • is there someone in team who could review your documentation and provide feedback?
    – gnat
    Dec 28, 2012 at 16:56
  • Having the need for this, sounds a lot like there are side effects in other methods that you are making explicit use of. Dec 29, 2012 at 9:08

3 Answers 3


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.

  • Thanks for the feedback! I'm thinking the "describe it's context" is looking like the best option for me. Thanks again.
    – loneboat
    Dec 28, 2012 at 17:52
  • 2
    Having a unique problem quite often means you're doing something the wrong way. Dec 28, 2012 at 17:58
  • 2
    @ThijsvanDien: Trust me, we're doing LOTS of things the wrong way around here! ;-)
    – loneboat
    Dec 28, 2012 at 20:08

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.

  • 1
    This answer should be the winner, except for the OP's original point that he's leaving the project and presumably has limited time and also presumably should not be introducing change on his way out. But absolutely correct - if something is complex enough to bear referring to externally, put it in its own named code unit. Dec 29, 2012 at 15:06

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.


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.