10
\$\begingroup\$

Over in , there are a set of style points that come up in almost every review of substance. I've found myself becoming more and more terse when raising those issues, which is ultimately a detriment to the people that are here looking for useful feedback.

I had the idea of adding some generally-accepted improvements, along with explanations and hopefully links to more official sources, to the tag wiki. These could be longer form, and answerers could link to them instead of re-explaining each time.

Rust also has some prominent tools that perform automatic formatting and linting. These tools tend to have documented rationale, and it would be great if people had the chance to know about them and run them. I figured I could add links to those as well.

Other languages also have official or semi-official guides. For example, Python has PEP8, Ruby has Rubocop, there are multiple style guides for Java and C++, etc.

When I went to edit the tag wiki, I found a bunch of introductory text that explains what Rust is. I think that at the point that someone is asking for a review of Rust code, they already know all that.

I found Would it make sense to copy (some) tag wikis from SO?, which seems to promote the process of copying tag wikis from Stack Overflow. Stack Overflow wikis are aimed at providing a high-level overview of the tag, but that doesn't seem useful here on Code Review. The top answer for 'Canonical' questions to help address common issues indicates that the tag wiki should be used as an entry point to frequent issues.

I believe there are two tightly-related aspects to this question:

  1. Should we put common style points relevant to a tag in the tag wiki?
  2. Should we remove/reduce aspects of the tag wiki that don't have to do specifically with code review?
\$\endgroup\$
  • 2
    \$\begingroup\$ One additional thought that came to me as I was writing this up: perhaps Stack Exchange Documentation is a proper place to house some of this repeated and semi-official information? \$\endgroup\$ – Shepmaster Oct 8 '16 at 17:02
  • \$\begingroup\$ The problem with docs is that they aren't integrated well outside of StackOverflow (read: not at all) ... In principle they'd probably be a good idea, but they're not ready for use here, so talking about it is dreaming of a future that could be ... \$\endgroup\$ – Vogel612 Oct 8 '16 at 17:43
  • 1
    \$\begingroup\$ @Vogel612 do you mean outside of Stack Overflow but inside Stack Exchange (e.g. here on Code Review) or outside of Stack Exchange (e.g. in Google rankings)? \$\endgroup\$ – Shepmaster Oct 8 '16 at 17:44
7
\$\begingroup\$

Yes, it would be a good idea to mention common code review issues in tag wikis.

I've done this, for example, with :

These sequences are sometimes called "hailstone sequences" because they can cycle between small and sometimes surprisingly large values before eventually arriving at 1. For example, the Collatz sequence for \$n = 159487\$ contains a number exceeding \$2^{31}\$, and would overflow a signed 32-bit integer type.

Please stick to objective non-controversial advice, such as official style guides.

Unfortunately, tag wiki texts are not easy to get to in the Stack Exchange UI, so they probably won't be discovered by most users spontaneously.


Unlike Stack Overflow, we currently don't have a large army of high-rep users to maintain the tag wikis, so I do tend to omit information that will easily become outdated.

\$\endgroup\$
  • \$\begingroup\$ "Unfortunately, tag wiki texts are not easy to get to in the Stack Exchange UI" do you recommend linking explicitly to the tag wiki in a review then? Starting with something like "In addition to the commonly raised review points that partly also apply to your code, I would like to point out…"? \$\endgroup\$ – I'll add comments tomorrow Oct 8 '16 at 20:38
  • 3
    \$\begingroup\$ @I'lladdcommentstomorrow as I read it, I'd continue placing my normal comments ("change foo to bar"), but I'd link those comments to the appropriate section of the tag wiki, so I don't have to retype the rationale each time. \$\endgroup\$ – Shepmaster Oct 9 '16 at 13:30
  • \$\begingroup\$ I have an edit pending that adds links to popular style tools. I've also started a list of common points. I think I'm going to try linking those points to a Stack Overflow Q&A that explains why it's better. That way, people can vote up / down or provide alternatives. \$\endgroup\$ – Shepmaster Oct 12 '16 at 19:25
  • 1
    \$\begingroup\$ @Shepmaster There's no way to get a link to a section of a tag wiki; it's only the one link to the page. :( Which is part of the problem here. \$\endgroup\$ – Laurel Oct 16 '16 at 18:30

You must log in to answer this question.

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