Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
    
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 '12 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. –  Michael Itzoe Dec 28 '12 at 16:50
5  
Wouldn't it be more expedient in these cases to just put the comments into the actual code? –  Robert Harvey Dec 28 '12 at 16:50
    
is there someone in team who could review your documentation and provide feedback? –  gnat Dec 28 '12 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. –  Ptolemy Dec 29 '12 at 9:08

3 Answers 3

up vote 1 down vote accepted

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.

share|improve this answer
    
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 '12 at 17:52
2  
Having a unique problem quite often means you're doing something the wrong way. –  Thijs van Dien Dec 28 '12 at 17:58
2  
@ThijsvanDien: Trust me, we're doing LOTS of things the wrong way around here! ;-) –  loneboat Dec 28 '12 at 20:08

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 documentaton, you can always create a seperate 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 artifical tags will become very difficult to maintain and even more difficult to understand for the uninitiated.

share|improve this answer
    
Thanks for the answer! –  loneboat Dec 28 '12 at 17: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.

share|improve this answer
    
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. –  Ross Patterson Dec 29 '12 at 15:06

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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