Does anyone have some opinions or advice about code blocks specifically for a diff or patch option?
I am working on some documentation that focuses on refactoring some existing code. I would think that diff blocks could do a good job at showing engineers exactly where to make their changes and exactly what those changes should be:
What I keep seeing is that when I then view the rendered result it's not always so easy for an engineer to then copy and paste that code. If an engineer tries to select the entire line to copy-and-paste to their IDE their clipboard captures the + indicator. This might not be so bad for one LOC… but if my code snippet instructs engineers to insert N lines of code the engineer then has to go and trim out N different + indicators. Not great.
I'm mostly targeting this to GitHub markdown… but it looks like DocC comments also display the same behavior where trying to copy the lines also copies the + indicators.
Any more advice for working around this? I'm looking for the best option to display a code block to the engineer and also give them an easy way to see where to make their changes and exactly what those changes should be.
FWIW any solution that I go with I would also like to optimize for accessibility purposes. Any solution I go with I would like to be at least as accessible as a diff block for engineers using any assistive screen reader.
If this is in a terminal window, many offer a “block selection” or “rectangular selection” mode. In macOS terminal apps, this can be done by holding down option+command while clicking and dragging the selection. (The exact key combination will vary based upon OS and terminal app.) Or you can copy the full lines, and then after pasting into your IDE, you can do this “block selection” within the IDE/editor, selecting the leading “+” and then delete all of those “+” characters in all of the lines with a single delete press.
Or you might consider reviewing these changes within some source control UI. E.g., if I copy-and-paste the changed lines from SourceTree, the leading “+” is not included in the copied text.
Alternatively, I might suggest a different workflow that frees the developer from manually incorporating the proposed changes in their branch (which is an inherently fragile workflow). Again, if viewing the diff changes in some source control app (e.g., I use SourceTree, but the same functionality is available in most source control apps), if not yet staged, the author can choose which hunk/lines to be staged. Or if already committed, they can review the changes in their source control app of choice, and choose which are to be “reversed”.
Also, if using a github “pull request” UI, the code author can choose to automatically incorporate the proposed changes into their branch, with no cutting and pasting required. See Incorporating feedback in your pull request - GitHub Docs.
If using git diff, there are options that don’t include the leading + and - (e.g., --color-words or --word-diff), so check those out. Or you can pipe the output of git diff through sed to strip these leading characters (but it then becomes a little awkward to figure out the context and what’s being inserted or deleted.
Those are a few ideas. If none of these quite address your problem, perhaps you can share more information about your environment, how you are handling pull requests (and whether you are using the github “pull request” UI), what IDEs, source control apps, and terminal apps you are using, etc.
These files containing +- differences are not intended for manual copy-paste. As far as I know, typically diff and patch commands are used. diff creates a patch file by comparing old and new versions of a file, and patch applies the differences in it to an old version of a file to produce new patched file.
Edit: Most likely you need to setup a version control system, like git - this will provide more advanced means of collaboration on the same files, than simple diff and patch utilities.