Skip to content

Instantly share code, notes, and snippets.

@Peilonrayz

Peilonrayz/Code Format.md Secret

Created April 17, 2019 09:54
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save Peilonrayz/cec502d641983b291c0319e00d7ba194 to your computer and use it in GitHub Desktop.
Save Peilonrayz/cec502d641983b291c0319e00d7ba194 to your computer and use it in GitHub Desktop.
Download ZIP
Wonderland 1.5
Raw
Code Format.md

I think the section Code Format should either be changed, or made into an [meta-tag:faq]. The list doesn't state that programming languages are on-topic as we've not had a meta discussion about them. And using well-defined terms helps reduce ambiguity meaning these questions are less likely to appear.

These types of questions can use a tag, [meta-tag:code-format], to allow users to search for similar questions.

The following posts should be moved.

  • From: off-topic > Code > Language Design
    To: Code Purpose
  • From: unknown > Multi
    To: Code
  • From: Code Location > off-topic > Presentation
    To: Code Format

Code Format

Note: The term 'is on-topic' only means that it is not off-topic for these reasons. But could be off-topic for other reasons.

When determining if your language is on-topic the simplest solution is to search our tags and see if you can find it.
Note: If there are a couple of handful of questions, you should check that the language is being reviewed in these questions, before using it as rational for your own post.

Specifying programs and versions

All code has to have something that allows us to run it. This means that we can verify if your code does what it is meant to, and also allows us to check our answer also work correctly. This means if this program is not available then we can't review your code. If this program doesn't exist then your code is classed as pseudocode.

Your code may require multiple programs to finally become runnable. A quick glance at modern JavaScript development should be all you need to know that this is fairly standard. This means that all of these program's should be available in regards to the above paragraph.

To ensure that your question is not pseudocode you can state all the programs required to run it, with their versions and plugins. However normally this is overkill, and tagging something with TypeScript and Less is sufficient.
Note: Regex requires you to state the engine you use.

Documents

We don't review documents, or things we don't count as code. This means asking us to review a presentation would be off-topic.1

If these documents contain code, then you should extract these sections of code out of the document into the post inline.

Our definition of code

It's hard to define what 'code' is exactly. But below describes what we think code is, and specifies any exceptions that we have. If this doesn't answer your question then check the [meta-tag:code-format] tag for if a similar question has been asked before. If it hasn't, then ask a question with that tag to find out if we think it should be on-topic.

The following are on-topic:

  1. Programming languages. This includes:

  2. Regex

  3. BNF

  4. Spread Sheets

  5. Documentation

The following computer languages aren't on-topic:

Determining if some languages are on or off-topic can be a bit tricky.

  • SQL is both a query language and a programming language. Since it's a programming language it's on-topic.
  • Awsome and Xmonad configuration files are also programming languages, Lua and Haskell respectively, and so are on-topic.
Raw
Code Miscellaneous.md

I think Code Miscellaneous could be grouped better. Rather than grouping by whether something is on or off topic, we should group by it's type first and explain when it is on or off topic. It should also include our rules on third parties. Making the following groups:

  • Context - One Liners, Incomplete Code, Insufficient Context.
  • Broken Code - Undiscovered Bugs, Broken Code.
  • Third Party
  • Golfed Code
  • Playgrounds
  • Bad Code

From here we can improve wording.

  • From: Code Location > off-topic > Third Party
    To: Code Miscellaneous
  • From: Golfed Code To: Review Type > off-topic > Golfed Code

Code Miscellaneous

Third Party

Whilst your code can originate from any where, we only provide reviews to code that is inline in question.

If your code was originally an answer to a Stack Overflow question or is opensource on GitHub, then you can still link to these. But you must include the code you want us to review in the Code Review question.

Broken Code

Broken code is code that doesn't run the way you intend. This code exhibits one of the following properties: [1]

  • cannot possibly compile even if other dependencies are included
  • fails to run
  • produces results that are obviously incorrect [2]

If you're an asker and you notice any of these, then your code is off-topic. You should fix these issues before submitting them for a Code Review. If you find one of these issues after posting your question that doesn't make your question off-topic. [3] And allows you or others to post a self-answer. [4]

Otherwise determining if a question exhibits one of these is a bit more nuanced.

  • The text of the question is a good starting point to find if the question is off-topic. Sometimes there's text sating that the code doesn't work the way they want and are asking us to fix it. Other times the question states a shortcoming which may make the code broken. Fairly frequently the question title is low quality and would be a title you'd expect to see on SO. These titles can say something that is extremely off-topic, but it's in regards to say readability. And so the code wouldn't be off-topic as it doesn't exhibit any of the properties from above.

  • When checking if the code alone is on-topic for the latter two reasons, you should ensure basic functionality is there. For example if someone posted n => n % 2 as a prime checker, whilst it would be correct for all primes, it would obviously be incorrect for a lot of non-primes, such as 9.

As you can see, this starts to become rather subjective from a non-asker's point of view. And so it's recommended to be lenient, could you see yourself unknowingly posting a similar bug when you were new to programming? [5]

Ultimately this comes down to community consensus through VTC and review queues. If you think something is off-topic VTC and see if others agree with you. It should be noted that it's recommended to post what you think is broken when VTC. This simultaneously improves the chances the question is closed, as now people can look at your comment rather than go through the entire process of looking for issues, only to miss what you thought was a bug. It also means that the asker can then fix the issue making their question on-topic.

Posting code with known issues

Sometimes you may want to get a review of code that has some issues, whether they be bugs or missing features. It's recommended to remove as many bugs and implement as many features as you can. But if they are small aspects of your overall code then that can be ok. [6]

Golfed Code

Asking a question about code that has been golfed or otherwise obfuscated is off-topic. [7]

If you want to ask a Code Review question about your Code Golf answer then you have to ungolf it first.

Swift Playgrounds

It is ok to ask questions about swift playgrounds. [8]

Bad Code

Since almost all code posted on Code Review could be classed as 'bad code', as most questions have been critiqued. It should make sense that 'bad code' is not off-topic.

It's also important to note that code is never 'too bad to review' [9] as the 'worse' the code the more important it is to review.

Context

On-topic:

Off-topic:

Unknown

Raw
Code Origin.md

I think the section Code Origin should be changed. For the most part we can defer to our close reason meta thread and our code ownership FAQ. I've added a short explanation around Generated code and code originally posted on Stack Overflow.

Code Origin

At code review we care about the origin. Not in the form 'where did it come from', but 'who wrote it'.

For moral, practical and legal reasons, we require you to be an owner or maintainer1 2.
Asking how code works is off-topic, and will be treated as if you aren't an owner or maintainer.

Generated Code

I wrote the code for ... site

If you contribute answers to this site or other sites, such as Stack Overflow1, it's allowed to also post your code as a question to this site. It is still subject to our close reasons.

Raw
Code Purpose.md

I think the section Code Purpose should either be changed. We can hide most of the links behind a tag like [meta-tag:code-purpose], this allows us to state some common examples, and hide the less common ones allowing a smaller section.

We should also explain example code as the only purpose that isn't ok.

The following posts should be moved.

  • From: off-topic > Code > Language Design
    To: Code Purpose

Code Purpose

For the most part you can post code that was made for any purpose.
Some notable examples:

  • Homework
  • Programming challenges
  • Interview questions
  • Libraries
  • Applications

Not on the list? For a list of topics that we've discussed you can look at the [meta-tag:code-purpose].

Example Code

The only thing we've disallowed is example code. This means if you've created some code purely as an example then it may be off-topic.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment