26

I'm looking for a tool with which I can annotate source code.

I have some 3rd party source code (JavaScript) I need to understand and I don't want to change it (add inline comments) so that

  • line numbers can stay intact (for communication with others),
  • I can avoid accidentally changing something and
  • my annotations stand out compared to the authors comments.

Normally I would print the whole thing out an scribble on it, but the code is too long for that and I need to share it per email. I would be great if one could do some like that including being able to create "links" between so places in the code, possibly even visually with a lines or arrows.

durron597
  • 31,968
  • 17
  • 99
  • 158
RoToRa
  • 37,635
  • 12
  • 69
  • 105

7 Answers7

16

If you would usually print it (if it were shorter), why not print it to a PDF and then use a PDF viewer that supports comments, like Foxit Reader? :)

OregonGhost
  • 23,359
  • 7
  • 71
  • 108
  • +1: certainly a better general-purpose answer than mine. – High Performance Mark May 21 '10 at 08:39
  • This sounds like an approachable way. I thinking of something similar with annotations in a word processor. – RoToRa May 21 '10 at 08:46
  • I uses Open Office to comment the code and keep it in this format for reviewing purposes. – Shivam May 26 '10 at 18:25
  • This is exactly what I thought of doing as I was reading the question. You could even combine this with the LaTeX suggestion to get pretty printing. To make collaboration easier and more "shared" you could look at uploading to scribd, but I'm not sure if that would be secure enough for your needs or if it allows the annotations you describe. – Chris Cleeland May 27 '10 at 20:59
  • I'm accepting this answer, despite that three new promising answers came in during the weekend. However I don't have the time right now to check them out properly before the bounty time runs out. – RoToRa May 31 '10 at 07:53
  • while this may be practical for this particular use-case, creating PDF out of plain text sounds like a nightmare for me - not because any difficulty in doing it, but because what it is. the enormous loss of the flexibility of plaintext. what about eg. editing? clipping some parts of the source but retaining context? pdf is like carving the result to stone. and if the source changes, I'm not sure, is it practically impossible to adjust the annotation? – n611x007 May 28 '13 at 11:31
4

I would use email to comment and pastebin to host and highlight @h@ lines with links in the email text.
OR
some code-review tool (like codestricker or reviewboard for example)

2

You can certainly do what you want to with LaTeX and its listings package. But if you are not already a LaTeX user you might think that a hard way to go.

High Performance Mark
  • 77,191
  • 7
  • 105
  • 161
2

start a github project and post the code there, github includes annotation abilities OOB.

Jason
  • 2,035
  • 11
  • 13
  • The annotations functionality are really good. I was very sceptical in the beginning, but now I am convinced they work great. – Peter Tillemans May 30 '10 at 20:05
  • 2
    Could you give a a link where this feature is described? I can't seem find anything on the github site. – RoToRa May 31 '10 at 07:50
1

You have difficult requirements. I don't know of such tool. Nevertheless as a more general purpose tool, I can recommend Yui Doc (download here).

ivo
  • 4,101
  • 5
  • 33
  • 42
  • Unfortunately I don't think normal documentaion generators will help me much. The code I have has heavy use of anonymous functions for closures, higher order functions and currying. – RoToRa May 21 '10 at 08:45
1

I'd build a glamour browser for it. (If spending half a day building it wouldn't be too much).

[edit] Glamour is a toolkit for building browsers on a model. The model would here consist of the various parts of the file(s) and the comments and attributes you'd like to add. This would allow you to easily navigate through the source and comments, to select only parts with (or without) certain attributes. There is a video and slides. Official page, Source

Stephan Eggermont
  • 15,847
  • 1
  • 38
  • 65
  • 1
    What is Glamour supposed to be? I've went over the web page several times und simply don't understand... – RoToRa May 29 '10 at 11:35
0

How about using google wave with syntaxy (http://wave-samples-gallery.appspot.com/about_app?app_id=14008) bot?

Maciek Sawicki
  • 6,717
  • 9
  • 34
  • 48