Guidelines for posting Tips and Tricks

Post your FreeBASIC source, examples, tips and tricks here. Please don’t post code without including an explanation.
Post Reply
counting_pine
Site Admin
Posts: 6323
Joined: Jul 05, 2005 17:32
Location: Manchester, Lancs

Guidelines for posting Tips and Tricks

Post by counting_pine »

Historically, the description text for this subforum has been: "Source code only - please don’t post questions here."
I think this was an attempt to just discourage people who were asking for "tips" on how to use FB. Questions like those really belong in Beginners or General, roughly depending on the difficulty level of the question.

But under this description, we’ve received a number of posts where people will indeed post "source code only", sometimes without comments, which wouldn’t always tell the readers how the code works, or even what it does.

The main purpose of this subforum is to teach or present ideas other people, rather than to just be an archive for people’s code.

For places to archive source code, source control sites like Bitbucket or Github provide a good way to store, search and share code, and provide a useful platform for collaboration. (Particularly Gist for short snippets or short-term projects.)
Or if you're not particularly interested in sharing your code or tracking changes, then something like Google Drive or Dropbox provide places to store your code online in case of hard drive failure, and also provide some sharing facility.


In line with this subforum's aim, I am writing some suggestions about how to post code, that might help people to write more helpful posts, and to touch more minds with their efforts:
  • - Include an introduction that explains what the code does, or what it demonstrates, or the problem it tries to solve. This may be the only part of the post that ends up getting read by many people, so it provides an important first impression.

    - Walk people through your code, using comments where needed, so they can understand how it works without having to compile and run it.

    - Make sure the code (or the important part) is easy to identify and reasonably easy to understand. This may not always be easy depending on the difficulty or length of the code, but of course when it's harder that makes a good explanation even more valuable.

    - If the code produces something visually interesting, consider uploading a screenshot somewhere and including it in the post. An interesting screenshot may inspire people to try the code themselves, and adapt it to produce interesting changes.

    - Finally, make sure that the code you post compiles and runs, and produces something worthwhile, to reward the people who have read your post and decide to try out your code.
My intention for now is that these would just be guidelines and suggestions, and not a set of rules that must be enforced.

I believe that the majority of people who post to Tips and Tricks are doing so because they believe it's a place for creativity. They have an idea or a small project they've worked on that they want to share with other people, and they want the people who read their posts to come away having learned something, or picked up an idea or code snippet they can work with or adapt. Or just to come away with a sense of appreciation of the work that's gone into the code and the post.

It is my hope that these suggestions will help the people who post here. If anyone has any other ideas that would help people write good posts, or you want to highlight examples of posts done well, then do please post them, but keep things constructive.
badidea
Posts: 2586
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Guidelines for posting Tips and Tricks

Post by badidea »

So, "Source code only - please provide explanation"?

Additional guidelines may include:
* Mention which external libraries are used (if not directly visible at the beginning of the code)
* Mention if files are created or if other disk I/O takes place (e.g. format c:)
Edit: Already included in your last point:
* Mention which other resources are required (e.g. bitmaps, data files)
* Check (before posting) if no custom include files are missing
Last edited by badidea on Sep 03, 2018 21:11, edited 1 time in total.
jj2007
Posts: 2326
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: Guidelines for posting Tips and Tricks

Post by jj2007 »

badidea wrote:* Mention which external libraries are used
There was a cute invention in the 20th Century called "hyperlinks". Can be used to point to the relevant downloads ;-)
badidea
Posts: 2586
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Guidelines for posting Tips and Tricks

Post by badidea »

jj2007 wrote:
badidea wrote:* Mention which external libraries are used
There was a cute invention in the 20th Century called "hyperlinks". Can be used to point to the relevant downloads ;-)
Where can I download the WINAPI? :-)
And I don't need links in most cases, just the library name to look it up in and install form the repository.

Which leads to an additional guideline:
* Mention target OS, if applicable and not obvious
jj2007
Posts: 2326
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: Guidelines for posting Tips and Tricks

Post by jj2007 »

badidea wrote:Where can I download the WINAPI? :-)
Google MSDN whatever, and you will always get the correct information.
And I don't need links in most cases, just the library name to look it up in and install form the repository.
The Internet is full of half-baken, obsolete versions of some library. Only the author who posted the snippet knows where the library is located that was used. And I definitely don't want to waste my precious time chasing libraries on the web just because the author was too lazy to insert a hyperlink, an act that takes about 5 seconds. Btw most library authors seem too lazy to explain in which folder their stuff should go. I hate that attitude because it forces me to do trial and error for something really trivial. It's a waste of my time.
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Guidelines for posting Tips and Tricks

Post by MrSwiss »

counting_pine wrote:- If the code produces something visually interesting, consider uploading a screenshot ...
I don't like the suggestion, because:
  • 1) uploading pics/images takes the surprise away (for those, running the code)
    2) uploading in and of itself, is a pain ...
    3) nobody will catch me, using a uploading site (any one)
Just my 2 Cents.
dodicat
Posts: 7976
Joined: Jan 10, 2006 20:30
Location: Scotland

Re: Guidelines for posting Tips and Tricks

Post by dodicat »

Badidea
I have just downloaded the winapi.chm from:
https://sourceforge.net/projects/win32-help-chm/

You need 7zip to extract it.
There is a link to 7zip on the web page.
badidea
Posts: 2586
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Guidelines for posting Tips and Tricks

Post by badidea »

dodicat wrote:Badidea
I have just downloaded the winapi.chm from:
https://sourceforge.net/projects/win32-help-chm/
It was actually a joke, but apparently a bad one. With linux as my daily OS, i have not much use for a WINAPI help file. Although I might but useful in combination with Wine (not the liquid in bottles) as well, if I ever plan to use that. But, this is all a bit off-topic.
deltarho[1859]
Posts: 4292
Joined: Jan 02, 2017 0:34
Location: UK
Contact:

Re: Guidelines for posting Tips and Tricks

Post by deltarho[1859] »

badidea wrote:i have not much use for a WINAPI help file.
I used to use mine to prop up one end of the bed when I suffered from acid reflux when I was very much younger. Boy, did I drink in those days! <smile>
jj2007
Posts: 2326
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: Guidelines for posting Tips and Tricks

Post by jj2007 »

dodicat wrote:I have just downloaded the winapi.chm from:
https://sourceforge.net/projects/win32-help-chm/
There is a much better version here. Same age btw - copyright 1996. Which is ok for 99% of all coding; if you need some of the recent functions, MSDN is your friend ;)
badidea
Posts: 2586
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Guidelines for posting Tips and Tricks

Post by badidea »

Shouldn't this topic be a sticky one (always on top)?
counting_pine
Site Admin
Posts: 6323
Joined: Jul 05, 2005 17:32
Location: Manchester, Lancs

Re: Guidelines for posting Tips and Tricks

Post by counting_pine »

I'm not sure yet whether this should be the official point of reference for posting here, but it's perhaps the best we've got for now, so I will Sticky it.
I can edit my top post if people think anything should be changed in it.
Tourist Trap
Posts: 2958
Joined: Jun 02, 2015 16:24

Re: Guidelines for posting Tips and Tricks

Post by Tourist Trap »

counting_pine wrote:I'm not sure yet whether this should be the official point of reference for posting here, but it's perhaps the best we've got for now
I think it's perfectly summarized. The essential thing is clearly understandable, the first post of any thread of this section should simply not be a question, or a too obfuscated piece of heavy metal that almost nobody will be able to understand. Otherwise, everything between the help advice and the small project seems to be very well located here.
Post Reply