Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/shlomif/how-to-share-code-online

How to share source code on online forums in order to get help with it
https://github.com/shlomif/how-to-share-code-online

code documentation forums getting-help guide hacktoberfest irc online-forums programming review tutorial

Last synced: 8 days ago
JSON representation

How to share source code on online forums in order to get help with it

Awesome Lists containing this project

README 

        
**WARNING!!** This file is now generated by make . DO NOT MODIFY directly!



# Motivation



This document aims to provide some general guidelines for sharing source code which exhibits an undesirable behaviour, in order for it to be reviewed and corrected on online forums.



# Guidelines



## Short, Self Contained, Correct, Example



First of all, your code should exhibit the problem you are having and should be a **self-contained**, and a **reproducing** example. More guidelines can be found in [“The Short, Self Contained, Correct, Example” (= SSCCE)](http://sscce.org/) page and in [Stack Overflow’s “Minimal, Reproducible, Example” page](https://stackoverflow.com/help/minimal-reproducible-example) (whose text is under [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/)).



### Reducing the code



If the code is too large, please consider reducing it to a more minimal example that still exhibits the problem (see the [bisection method](https://github.com/shlomif/Freenode-programming-channel-FAQ/blob/master/FAQ_with_ToC__generated.md#what-does-bisecting-mean) ). Namely, you can try gradually removing parts of the code while each time ascertaining that the problem can still be reproduced until you have reached the shortest possible code. Often, doing that will be enough to find the culprit reason for the failure and to fix it.



## Show the Whole Code



Please don't share non-runnable pieces and fragments of your code, see [“Show Us The Whole Code”](http://shadow.cat/blog/matt-s-trout/show-us-the-whole-code/) .



## Share code - not screenshots



As a general rule, it is a better idea to share the code as text, as that can be compiled and run.



When you do need to share [screenshots](https://en.wikipedia.org/wiki/Screenshot) of the code, try using a screenshot tool such as the keyboard Print-Screen button. That is because using a camera (for example, that of a smartphone) to photograph the screen, will reduce the quality and faithfulness of the image. See:



- [“The Easiest Way to Take a Screenshot in Windows \| wikiHow”](https://www.wikihow.com/Take-a-Screenshot-in-Microsoft-Windows)



- [“How to take screenshots on Fedora Workstation - Fedora Magazine”](https://fedoramagazine.org/take-screenshots-on-fedora/)



## How to upload the code



If you are coding a web page, you can try sharing your code using [jsfiddle](http://jsfiddle.net/) .



Otherwise, if your code is self-contained in one file, you can use a paste site such as [ideone](http://ideone.com/) or [paste.debian.net](https://paste.debian.net/). If you are using an IRC chatroom (which are also called “IRC channels”), don't floodpaste the code to the channel because this is slower and more annoying than using a paste site and may get you kicked or devoiced out of the channel.



If the code you are sharing is a reusable component, you can use [Bit](https://github.com/teambit/bit) to isolate it and share it so that it can be installed or imported in other projects.



Some other types of forums allow you to quote a single and self-contained codebase using a notation such as [the HTML “pre” tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre), or using [indentation](https://github.com/shlomif/Freenode-programming-channel-FAQ/blob/master/FAQ_with_ToC__generated.md#what-does-indentation-mean) or triple-backquotes, so it may be an option there depending on the forum’s policy.



If you have more than one file in the project, then you should put it in a self-contained version control repository on a code sharing site such as [GitHub](http://github.com/) , [Bitbucket](http://bitbucket.org/) , or [GitLab](https://about.gitlab.com/) , so people can easily clone or checkout it.



## Use a Continuous Integration (CI) Service



If you have the time, and solving the issue is important for you, you should set up a public [CI service](https://github.com/shlomif/Freenode-programming-channel-FAQ/blob/master/FAQ_with_ToC__generated.md#what-do-continuous-integration-ci-services-such-as-travis-ci-jenkins-or-appveyor-provide) with a build and test script, and which reproduces the issue. This way, other people will have an easier time reproducing it.



## Put the code under a usable copyright licence.



See ["which licence should I use"](https://github.com/shlomif/Freenode-programming-channel-FAQ/blob/master/FAQ_with_ToC__generated.md#i-want-to-release-my-code---which-open-source-licence-should-i-use) .



# Links



- [Freenode’s \##programming channel FAQ](https://github.com/shlomif/Freenode-programming-channel-FAQ/blob/master/FAQ.mdwn) - where this document originated from, and which may contain some other insights.

- [Writing the Perfect Question](https://codeblog.jonskeet.uk/2010/08/29/writing-the-perfect-question/) - by Jon Skeet

    - [How to ask questions the smart way](http://catb.org/~esr/faqs/smart-questions.html) - an older resource with a somewhat condescending tone

    - [Getting Answers](https://www.mikeash.com/getting_answers.html) - a guide by mikeash.com, which unfortunately suffers from using too many obscure Apple APIs as examples.

- [How to Get Help Online](http://www.shlomifish.org/philosophy/computers/how-to-get-help-online/) - recommended venues.



## Project Links



- [Canonical URL for the document](http://www.shlomifish.org/philosophy/computers/how-to-share-code-for-getting-help/) - on Shlomi Fish’s home site. That page should validate as XHTML 5.

- [GitHub repository](https://github.com/shlomif/how-to-share-code-for-review) - contains the DocBook/XML sources, an issue tracker and more resources. Contributions are welcome.