0

I often have this problem, coding in C or Python: I start writing an expression, and it starts with a simple line comment, so far so good; say:

// initiate sending to hardware:
hardware_send_init(&data_to_send);

... however, as things get more complicated, I can end up having quite a bit of comment text for a single line - to the point it gets unreadable:

// initiate sending to hardware:
// since blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// we must also specify `flags`;
// and since blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// we must also use num_items:
hardware_send_init(&data_to_send, flags, numitems);

So, now that this is unreadable, I often come up with some string marker for comment references, say ((*comment_NUMBER*)), and I basically cut the comments and move them to the end of the document, and add a reference in comment at the original location:

hardware_send_init(&data_to_send, flags, numitems); //((*comment_05*))
...

// (end of code)

//

//((*comment_05*))
// initiate sending to hardware:
// since blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// we must also specify `flags`;
// and since blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// blah blah blah blah blah blah
// we must also use num_items:

So, this is fine, in the sense that comments and code are still in the same document, and I can easily look up //((*comment_05*)) as a unique "ID" string with CTRL+F - but then, I loose the "flow" of code with comments.

So I thought, a good solution for me, would be some sort of a double-pane GUI software, where in the left pane I'd get the code -> and if I click to position the cursor on a comment marker (say, //((*comment_05*))), then the corresponding comment is brought into focus in the right pane -- here is how I imagine this in a mockup, made with Notepad++ ("to split the Notepad++ window into two sub-windows, right-click on an open tab, then click “Move to Other View” or “Clone to Other View”."):

notepad++ dual pane

Even if Notepad++ itself could be used for something like this with CTRL+F, it is still a bit tedious (especially since once you've found your tag, you have to click around to have the lines align).

So, I was wondering, if there is already an existing source code editor (I'm interested in cross-platform, but would like to know if this kind of functionality is present in any editor on any platform at all) - or a plugin for one, that allows for this kind of functionality:

  • defining a string template for code comments reference marker (possibly as a regex); and then
  • identifying all such markers in the currently open text/source code document, and
  • jumping to the definition (actual comment text) in right pane, if a comment reference is selected (in most basic form, just placing the cursor in the comment reference string should be enough) in the left pane (and vice versa, iff there are exactly two instances of a given marker in a document).

Sidenote: I've been also reading about Dr. Knuth's literate programming, specifically Web (programming system) or rather CWEB, an example of which can be found in https://github.com/agl/critbit : from a .w(eb) file, you can either generate a .pdf documentation file (via .tex) - or a .c file, which has comment markers like /*:7*/: while I really like such separation of comments/documentation and code, and I could adjust my workflow to writing .w(eb) files first - it would be difficult to get colleagues on board... Unless there is software, that could automatically determine the .w source when a .c file is opened, and similarly to the principle above, "jumps" to the right comment in the right pane, when the comment reference is selected in the left pane. But the above approach still has the advantage, that the code and the comments are self-contained in the same source file, and CTRL+F functionality is still there with typical text editors, even if the dual pane convenience is not

2
  • 1
    In my opinion non-clickable references to comments at the end are not a good ide. May be it would be better to search for an editor that is able to fold comment blocks that are larger than one line?
    – Robert
    Commented Nov 23, 2022 at 13:13
  • Thanks @Robert - I was maybe unclear, I did not want "non-clickable references" but the opposite, "clickable references": I was just trying to emphasize, that I don't even need additional UI chrome (e.g. references formatted specially, maybe blue and underlined like hyperlinks; mouse pointer changes on hover), it would be enough for me to just click to place the text cursor somewhere in the reference, and have the "click" executed (that is, referenced comment aligned and shown in other pane).
    – sdbbs
    Commented Nov 23, 2022 at 22:44

0

Your Answer

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