We need a standard for referencing and linking to source code

[willihay]

Thought it might be useful to preserve a discussion on this in the sig repo, for easy reference later.

I did not see anything under the Style guide inside the O3DE Contributor Guide regarding a standard format for references and/or links to O3DE source code. This has come up a number of times in the O3DE User Guide, and there is no consistent format as of yet.

Choices include:

1. File path layout (Gems/Example/Code/File.cpp) or GitHub source URL (https://github.com/o3de/o3de/blob/development/Gems/Example/Code/File.cpp).
2. Branch (main or development) - presume we should default to development, since that might be the only place it exists when the doc is written.
3. If GitHub URL, simple link or permalink.

Formats I've seen:

1. Simple file name reference:

   Gems/StartingPointInput/Code/Source/InputLibrary.cpp

   Pros: Shortest format. Relatively easy to open if you have the source on a PC. Could be used as the "text" part of a Markdown link.
   Cons: Not everyone will have the source on their PC.

2. Simple link to a source file on GitHub, with or without line number/range:

   • https://github.com/o3de/o3de/blob/development/Gems/StartingPointInput/Code/Source/StartingPointInputGem.cpp
   • https://github.com/o3de/o3de/blob/development/Gems/StartingPointInput/Code/Source/StartingPointInputGem.cpp#L118
   • https://github.com/o3de/o3de/blob/development/Gems/StartingPointInput/Code/Source/StartingPointInputGem.cpp#L118-L123

   Pros: Clickable link. Supports opening to a line number.
   Cons: Since it's a clickable link, it's prone to breaking. The referenced code might move to a different line number, or be deleted.

3. GitHub permalink (i.e. specific commit) to a source file, with or without line number/range:

   • https://github.com/o3de/o3de/blob/e7ba95094bff89fc24431c373d079af186d13bf7/Gems/StartingPointInput/Code/Source/StartingPointInputGem.cpp
   • https://github.com/o3de/o3de/blob/e7ba95094bff89fc24431c373d079af186d13bf7/Gems/StartingPointInput/Code/Source/StartingPointInputGem.cpp#L118
   • https://github.com/o3de/o3de/blob/e7ba95094bff89fc24431c373d079af186d13bf7/Gems/StartingPointInput/Code/Source/StartingPointInputGem.cpp#L118-L123

   Pros: Clickable link. Always valid. Supports opening to a line number.
   Cons: Longest format.

Others?

My preference is leaning towards this combo format:

Gems/StartingPointInput/Code/Source/InputLibrary.cpp

OR

Gems/StartingPointInput/Code/Source/InputLibrary.cpp, Lines 118-123

[FiniteStateGit]

I'd prefer the combo format. I think any reference to a specific line number has the potential to be problematic, I'd prefer an adjacent description of the section to be sought out, "In the Reflect function of the StartingPointInputSystemComponent class".

If a small section of code needs to be referenced, wouldn't it be easier just to have a snippet on the page?

[willihay]

I agree we should avoid using any text reference to line numbers. I like the idea of encouraging writers to reference functions or classes when needing something more specific than file names.

Snippets might be preferable in some instances, such as from source where the code is unlikely to change, or when a specific implementation or algorithm is being referenced. One of the advantages of a link over a code snippet of course is that oftentimes, the implementation can change and a link will still be valid; and if we use a permalink, at least the link will always be valid (although the code could change, haha). Perhaps the choice could be encapsulated in a well-thought-out guideline.

[chanmosq]

Do you mean - snippets are preferred when the source of code is likely to change?

[willihay]

No, if the code (meaning the implementation) is likely change, I think there's all the more reason to use a link to GitHub source or just a mention of the file location.

[chanmosq]

Oh I see what you mean. What I was thinking of is another issue to consider when deciding whether to provide a GitHub link or a code snippet: If the source code location is likely to change, then it's better to have a snippet.

[willihay]

Okay, yeah that makes sense and I would agree with that. Probably makes sense to cover all of these scenarios in any resulting guideline.

[chanmosq]

For format, I like the combo.

Agreed with willihay regarding when to use code snippets vs. link to GH.

Any code snippet that references source code should have a link or path to the file. For example, macro definitions or settings registry. It's incredibly useful to know where we can find these.

We'll need to audit the docs for ambiguous filenames that don't have an explicit path or link to GH.

I think code snippets should be short (~5 lines). If any longer, it'd be good to consider turning a code snippet into a link to source code. For long code snippets that don't reference the source code, such as for tutorials, they should highly consider turning it into source code we can link to instead. For example, by creating a usable code sample via a Gem.

Links to code should always have contextual text, specifically the path name or file/directory name. It should never be written as "here" or "this"; for example, it shouldn't be "checkout the code here."

[willihay]

Thanks for the feedback, @FiniteStateGit and @chanmosq. I've put a recommendation into a new GitHub issue, based on our discussion: o3de/o3de.org#1926