[Tutor] Sharing Code Snippets

[Steven D'Aprano]

On 11/04/13 11:28, Amit Saha wrote:
> Hello everyone,
>
> I am not sure if this has been shared on this list. However, to help
> both those seeking help and those wanting to help, may I suggest that
> for all of you posting your programs, how about using a service such
> as GitHub's Gists [1]. It allows you to post entire programs with
> advantages such as intact code formatting, syntax highlighting and
> perhaps others such as version control.


Please don't. Small code snippets should be posted directly in the
body of the email, not on some external website.

They should be posted in PLAIN TEXT (do not use so-called
"rich-text", HTML formatted emails, since they destroy critical
indentation and make it difficult for those using plain-text email
clients to read your code). Like this:


import random

def coin_toss():
     if random.random() > 0.5:
         return "head"
     else:
         return "tail"


It's much less work for everyone to read code snippets in the email:
compare:

SENDER: copy and paste code directly into email

READER: read email
         write response


versus:

SENDER: open browser
         log in to external site
         copy and paste code into external site
         make sure code has been saved
         copy and paste url into email

READER: read email
         open browser
         copy and paste url
         fix url if it has been mangled by line-wrapping
         read code
         copy and paste back to email for the response


to say nothing about how it may effect those who use a screen reader. (They
generally work well with email, not so well with many websites.)

People may have access to their email, and be able to read and answer your
question, but they may not have access to the web. Perhaps they are behind
a firewall that blocks the website. For whatever reason, just because
somebody is reading your email doesn't mean that they can or will follow
to a website to read the important bit (the actual code). You should make
it *easy* for people to answer, not harder.

Code sharing sites are great for posting entire programs, but you, the
reader, shouldn't be posting entire programs and expecting us to work out
where the problem lies. Identify where the problem lies, and eliminate all
unnecessary code. Please read this for more details:

http://sscce.org/


-- 
Steven