Github, in-code questions in a pull request

Question

In the context of an open source project, I started annotating lines of code that had issues or that I didn't fully understand with question-containing comments. Eventually, I reasoned, I would issue a Pull Request (on github) and use its discussion facilities to solicit answers, change the code where appropriate and eventually remove the questions.

As issuing a Pull Request with questions wasn't the project's typical way of doing things, together with other contributors we have been wondering if it is a practice that would be appropriate to adopt or if there are good enough reasons to avoid it instead.

So far the project has relied on its forum for code-related questions. In this scenario lines of codes are quoted in a post or referred to via links to specific lines in a github repository. The obvious disadvantage of this method is that is slow, useful only for discussions about relatively few lines of code. An alternative has been to issue a PR, potentially with only small even insignificant changes (i.e. a single blank space), and use the discussion facilities to ask the questions. A disadvantage of this method, at least on github, is that the lines the discussion refers to are -not- highlighted, leading to confusion in the case in which a comment added through the PR interface does not refer to one of the clearly highlighted diff lines visible nearby. This method is also not particularly fast as the questions will generally be written somewhere first and then have to be copied-in after the PR has been issued.

In this context, adding questions straight into the code and answering to them via the PR discussion interface keeps code, questions and answers in short distance of each other. But also has the disadvantage of "dirtying" at least some commits of a branch with comments that are known to be temporary.

Are there other advantages, disadvantages and best-practices to consider to settle the matter?

Answer 1

Imo, starting a pull-request on Github for asking particular questions about some code (lines, blocks, sections) is not the best practice:

1. the repository gets polluted, as in order to start a PR you have to push at least some minor changes onto you repository
2. code comments can get outdated, i.e. not be shown in the Github conversation anymore (directly) due to further commits

What about working with Github gists and linking them with specific issues?