[question] Marking code snippets inside source code files?

[maxbrito]

Hello,

Sometimes I find snippets of code on a source file deriving from some third-party. Preferably, I'd like to document them down to the line position so that it can be referenced for human or automated analysis later.

How would I specify this scenario inside an .ABOUT file?

Couldn't find the specification approaching this point, my apologies if I missed something in the available examples and docs.

My thanks in advance. Nuno

[pombredanne]

@nunobrito the topic of snippets has not been included in the spec on purpose. Here is the rationale:

• A file containing third-party code snippets is always from mixed origins and possibly mixed licenses meaning that the whole file would usually require some combined attribution
• Also, from a redistribution perspective if the snippet is copyleft-licensed, the copyleft license would usually apply to the whole file and not only to the snippet.

Therefore the simplest way is to document things at the whole file level.

In general documenting the location of an actual code snippet is best done directly in the code with appropriate comments, though we never want to have to modify code for the purpose of documentation therefore the typical way is to use an ABOUT file for the file containing snippets and to create a composite notice and license that applies to the whole file.

Additional documentation could be done additional using:

• a note
• custom field(s) such as start_line end_line

Note: snippets could be explicitly supported in future versions if you feel strongly about it.

Does this make sense to you?

[maxbrito]

Hi Philippe, thanks. Your reply makes sense.

though we never want to have to modify code for the purpose of documentation

Yes, agree. Modifying code is sometimes off-boundaries during analysis.

the typical way is to use an ABOUT file for the file containing snippets and to create a composite notice and license that applies to the whole file. (...) Note: snippets could be explicitly supported in future versions if you feel strongly about it.

What I'm usually asked is to first document the non-authored snippets of code. Then on basis of that list, management decides what to remove, rewrite or investigate further because provenance costs them more than development. Not much chance to track down the author/license in detail.

I document these snippets on a word document, sometimes a text file to keep quick track but this isn't a standardized procedure. The procedure you mention with a custom field and notes is good enough to get started and test an implementation.

At this point I'm still looking for different approaches to document non-original code snippets. Will later propose an enhancement after more testing on the matter. Thanks for the help.

[grv87]

PEP 350 tried to mark code parts with various tags. Including CRED/THANKS.

That PEP was rejected. But maybe it can be used as an example.

[pombredanne]

@grv87 excellent reference! There is also https://spdx.org/ids that did not exist back then?

[grv87]

@pombredanne, yes, it did not. Also, Python guys didn't consider licensing and copyright at all.

I tried to use PEP 350 approach in practice. There is a problem that it doesn't have ending tag. So, in my project borrowed code starts with /* CRED ... <> and ends with something custom // End of borrowed code. Ugly. So, I'm in a look for solution too.

[grv87]

Found this practice: https://docs.unrealengine.com/en-US/Programming/Development/CodingStandard/index.html#thirdpartycode

// @third party code - BEGIN PhysX
#include <physx.h>
// @third party code - END PhysX
// @third party code - BEGIN MSDN SetThreadName
// [http://msdn.microsoft.com/en-us/library/xcb2z8hs.aspx]
// Used to set the thread name in the debugger
...
//@third party code - END MSDN SetThreadName

This could be combined with SPDX Snippet tags.

I would also like to point to fsfe-reuse. Now it is able to walk all files in the project, parse SPDX license and copyright tags in file headers and generate the whole SPDX manifest. It should not be hard to add parsing snippet tags there. And then, @maxbrito, you'll get your list of all borrowed snippets.