2
\$\begingroup\$

I am working on an open-source library that contains several source files. I would like to ask for feedback, not only for specific code in specific files, but also on the more general arrangement of the library and the dependencies between modules. I saw that most questions on the site ask about code that is contained in a single source file. Can I ask for feedback on the library, even though it contains several files?

\$\endgroup\$
2
  • \$\begingroup\$ Does the open source community currently exist, or are you trying to create it? I thought open source libraries had communities to review the code prior to release. \$\endgroup\$
    – pacmaninbw
    Feb 28 at 16:25
  • \$\begingroup\$ @pacmaninbw It is a new library, so it does not have a community yet. \$\endgroup\$ Mar 1 at 7:24

2 Answers 2

4
\$\begingroup\$

Lets break down your question into separate and more digestible parts.

  1. Are reviews of libraries allowed? yes
  2. Are large questions allowed? ("an entire library", "contains several files") only if your question fits within the 65535 character limit.
  3. Is asking for feedback on specific code allowed? yes
  4. Is reviewing design on-topic? Yes, if you provide code.
  5. Is project structure (file system) on-topic? Yes, if you provide code. An fs tree is not code.

So a conclusion is; "yes, if you include the code in your question."

However the above questions aren't really the same as the OP's question. As I've been very literal. Like when you ask the question "can you pass the salt?" All I've done is say "yes, I posses the capacity to pick up and pass the salt to someone." Yeah, not very helpful.

The thing is, I've focused on if your question is on-topic. Completely blinding you from other rules which can leave you with a sub-par experience. Whilst you can ask for specific feedback reviewers can comment on anything. This has been documented on Code Review Meta a number of times:

  • I believe telling about things people don't ask for is a huge part of a good code review. Of course, it should be both polite and helpful.

  • Do we want to tell people about things they don't ask for or is that considered impolite / frowned upon / bad behavior?

    If you tell someone something they don't already know, then you helped increase their knowledge in something. That can't hurt, right? Plus...isn't that the idea of Code Review? To help people improve their code? Why would it matter if you address something they didn't ask about; especially if it improves their code.

  • Yes. It is fine to ask reviewers to preferably avoid commenting on something.

    Of course the reviewers can comment about it anyway, and then it will be up to the community - and the original poster - to determine if the review is helpful or not.

  • One of our Help Center rules, and indeed, one of our core values, is

    Do I want the code to be good code?

    To that end, any answer that makes the code "better" is fair game. It's just that this OP has declared some preconceived ideas of what is "better", so you would have to work extra hard to convince them to abandon the self-imposed constraints.

  • Yes, it is implied with every Code Review question that "any and all aspects of the question can be reviewed". From the help center:

    • Do I want feedback about any or all facets of the code?

    As a consequence, any answer that addresses any aspect of the code, whether the user asked for that aspect, or not, is acceptable as an answer.
    rolfl, CC BY-SA 3.0, Is it okay to give a review without actually answering some of the OP's requests?

If we ignore the specifics of each point we can summarize the rule as "but we may not provide the review you want." Lets focus on why this may happen; Mathieu Guindon's Zombie Ratings. The library you've described sounds like "The Project Review Project" with a zombie rating of 3. Meaning your question is likely to go unanswered.

Now lets pretend you have a file called garbage.py, filled to the brim with working code which can only be described as garbage. There's enough wrong we could write a short book on the issues in the one file. Pointing out the low hanging fruit in garbage.py will be easier than tackling the project as a whole, dropping your zombie rating from 3 to 1. You're more likely to get an answer, but even less so about the general arrangement or module dependencies.

When asking for design reviews you need to be careful. Whilst design reviews are on-topic, sharing too much unrelated code increases the zombie rating of your code. And if the quality of the somewhat unrelated code is poor then you're less likely to get the review you want. So, whilst you can just dump all the code, you should take the time to take only the important parts of your code and try to make the code as clean as you can.

\$\endgroup\$
5
  • \$\begingroup\$ If I understand correctly, all code should be copied & pasted into the question? Is it not allowed to give a link to a GitHub repository? \$\endgroup\$ Feb 20 at 15:15
  • 1
    \$\begingroup\$ @ErelSegal-Halevi You should really craft the question to your needs, so even if you could just link to GitHub I wouldn't recomend so. However, you must include the code in the question and we will not edit the code into the question. \$\endgroup\$
    – Peilonrayz Mod
    Feb 20 at 15:19
  • \$\begingroup\$ What about documentation in Markdown files - should I also copy it into the question? (it is an important part of the code, but it is in a non-code file, and is easier to read on GitHub). \$\endgroup\$ Feb 20 at 15:21
  • 1
    \$\begingroup\$ @ErelSegal-Halevi If you don't include the documentation in the question you're just increasing your zombie rating. You can omit the documentation. But similarly, you can always shoot yourself in the foot. \$\endgroup\$
    – Peilonrayz Mod
    Feb 20 at 15:28
  • \$\begingroup\$ @ErelSegal-Halevi The problem with relying on GitHub is people move their repositories all the time. Links break. It simply won't do for those parts that have to be in the question itself. \$\endgroup\$
    – Mast Mod
    Feb 20 at 20:39
1
\$\begingroup\$

I have posted 25 questions on Code Review, 24 have been answered. 23 of the questions are non trivial (multi file questions). You will get an answer in time, it may not be as fast as you want. As a suggestion ask multiple questions, one about each source file with necessary header files if that applies. Provide a link to the repository in each question. As far as interfile dependencies go, the last question you ask should be about the file that ties most of the library together, ask your dependency question there.

\$\endgroup\$

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .