Jump to content




Ask A Pro Renewal Project (and How You Can Help!)


115 replies to this topic

#21 Engineer

  • Members
  • 1,378 posts
  • LocationThe Netherlands

Posted 03 August 2013 - 03:57 AM

View PostSora the Hedgehog, on 03 August 2013 - 02:31 AM, said:

Both drafts look good, but a guideline for the posting advice :
"When you are posting your code, please take a minute to format it (indentation, etc) for readability. This will help us understand your code faster."
Waaay too often do I see code that hasn't been indented. That stuff is so hard to read. You'll probably want to explain what exactly formatting means within this context, maybe in it's very own section even.
However it is very helpfull, there are tools available to automatically indent. I wrote with GravityScore some decent indenter, but it doesnt indent the table. After this shameless self-plug I also want to point out that there is an auto-indenter built in with Sublime Text. There are probably more tools to indent the code.

But I do agree it adds to the helper if the code is already properly formatted etc. The help then comes faster, I just wanted to point out that there are tools available to indent code.

#22 Sora Firestorm

  • Members
  • 89 posts

Posted 03 August 2013 - 03:47 PM

Sure, run it through tool xyz to format it, do it by hand, whatever. Format it somehow.

#23 Lyqyd

    Lua Liquidator

  • Moderators
  • 8,465 posts

Posted 03 August 2013 - 06:01 PM

Here's a draft of a "get help faster" section:

Generally, both in Ask a Pro and elsewhere, the amount of effort people are willing to put in to answer a question is dependent on how much effort it looks like the asker has put in to forming the question. This is for two reasons; people are more willing to help someone who seems to have put in effort trying to find the answer themselves, and it is easier to find a solution to a well-formed question than to find an answer to a poorly-formed question.

One major thing you can do to improve the quality of your question is to ensure that your code is well-formatted. Indentation especially will help, as it makes your code vastly more readable and much easier to follow. It is also easier to spot mismatched code blocks (extra `end` statements, or too few of them) and other problems. Here is an example of how to indent:

Spoiler

In addition to well-formatted code, a description of your program and what it does or is supposed to do can be helpful for figuring out the intent behind the code. A good explanation of what the code currently does is very useful along with a description of what you expected it to do instead, or what you'd like it to do. This information also is very helpful for us to be able to provide you with the best answers we can. Also, see the tips about choosing a good topic title in the previous section.

#24 immibis

    Lua God

  • Members
  • 1,033 posts
  • LocationWellington, New Zealand

Posted 03 August 2013 - 07:47 PM

I would add:

vm error: ArrayIndexOutOfBoundsException
Do not call a function inside itself, directly or indirectly, unless you know what you're doing. This also applied to programs when using shell.run.
There is a maximum depth of function calls. If you have a function that calls a function that calls a function that calls ..... that calls a function that calls a function, and there are more than 256 functions being called, your program will crash with this error.


(Btw, this problem singlehandedly changed my mind about goto - it might be bad practice for writing large complex programs, but for learning purposes it's the simplest control structure to understand, and it's obviously better than using functions as if they were goto.)

#25 Bubba

    Use Code Tags!

  • Moderators
  • 1,142 posts
  • LocationRHIT

Posted 03 August 2013 - 07:59 PM

View Postimmibis, on 03 August 2013 - 07:47 PM, said:

I would add:

vm error: ArrayIndexOutOfBoundsException
Do not call a function inside itself, directly or indirectly, unless you know what you're doing. This also applied to programs when using shell.run.
There is a maximum depth of function calls. If you have a function that calls a function that calls a function that calls ..... that calls a function that calls a function, and there are more than 256 functions being called, your program will crash with this error.


(Btw, this problem singlehandedly changed my mind about goto - it might be bad practice for writing large complex programs, but for learning purposes it's the simplest control structure to understand, and it's obviously better than using functions as if they were goto.)

Added. Also added multiple points error.

#26 Lyqyd

    Lua Liquidator

  • Moderators
  • 8,465 posts

Posted 03 August 2013 - 08:44 PM

Changed the phrasing for overflow and multiple points errors to better match the explanation-of-error style used in the others.

#27 Sora Firestorm

  • Members
  • 89 posts

Posted 03 August 2013 - 10:04 PM

While the 'Get Help Faster' segment that you've written looks good already, Lyqyd, I'd also talk about spacing.

Taking code that looks like this :
local e,p1,p2,p3,p4,p5=os.pullEvent();
if e=="event_wanted" then
  -- More code with horrible spacing here
end
moreStuff();

and transforming it into something like this :
local e, p1, p2, p3, p4, p5 = os.pullEvent();

if e == "event_wanted" then
  -- More code with good spacing here
end

moreStuff();

The line breaks being where they are is more of personal preference, but keyword spacing is a must.

#28 Bubba

    Use Code Tags!

  • Moderators
  • 1,142 posts
  • LocationRHIT

Posted 03 August 2013 - 10:21 PM

View PostSora the Hedgehog, on 03 August 2013 - 10:04 PM, said:

While the 'Get Help Faster' segment that you've written looks good already, Lyqyd, I'd also talk about spacing.

Taking code that looks like this :
local e,p1,p2,p3,p4,p5=os.pullEvent();
if e=="event_wanted" then
  -- More code with horrible spacing here
end
moreStuff();

and transforming it into something like this :
local e, p1, p2, p3, p4, p5 = os.pullEvent();

if e == "event_wanted" then
  -- More code with good spacing here
end

moreStuff();

The line breaks being where they are is more of personal preference, but keyword spacing is a must.

To be honest, I do not find the variable spacing distracting at all. They're really both personal preference and I think that most people are capable of comprehending the code either way.

#29 Lyqyd

    Lua Liquidator

  • Moderators
  • 8,465 posts

Posted 04 August 2013 - 01:11 AM

I think indentation preferences have more in common from person to person than line spacing preferences do, to be honest. It's really more about helping essential readability, and I think that proper indentation is one thing that makes a huge difference depending on whether it is present or not, much more so than line spacing does. I suppose if it becomes a problem, we could add something about it.

#30 Sora Firestorm

  • Members
  • 89 posts

Posted 04 August 2013 - 04:56 PM

I like to think of proper spacing as already having the string tokenized to be read. Sure, one can do this themselves, but I feel like it takes more effort than is necessary to tokenize it yourself. But whatever. I'm not going to try to force my point.

On a side note, I've been watching the 'People Answering Quesions, Please Read' thread, and I noticed it's managed to sink in to the second page. My goal is to have this page stickied, so if there is anything else I need to do to get it 'sticky-quality', please tell me.

#31 Lyqyd

    Lua Liquidator

  • Moderators
  • 8,465 posts

Posted 04 August 2013 - 05:50 PM

I'm not really sure what you mean about "tokenizing the string to be read" in regards to line spacing. :)

We don't pin posts where the OP is not at least a moderator, having been burned by giving a normal user edit access to a sticky post before. The content is good, though I'm not sure it's quite precisely what we're looking for. It feels a little prescriptive still, and I think Bubba and I both have writeups in mind to cover the same topic, so we will compare the two or three of them once they're done and come up with a final product that will convey what we want best. Your post was certainly valuable though, so thank you for taking the time to write it up. If you wanted to copy and paste it over to here in a separate post, it would remain easier to find.

#32 Sora Firestorm

  • Members
  • 89 posts

Posted 04 August 2013 - 08:55 PM

Sounds good to me. I understand that you'd rather not sticky the post, and that's fine. What fun is getting stickied when my post isn't the best? :)

For posterity :
Spoiler


#33 GopherAtl

  • Members
  • 888 posts

Posted 05 August 2013 - 01:41 AM

I've gone over your list of tutorial topics in the OP several times, and I wonder if it might not be worthwhile separating the concept of a tutorial and an example.

A tutorial would be primarily text, with code snippets mixed in, but an emphasis on explaining the concepts. A tutorial may or may not result in a final, useful program by itself, but it will always thoroughly explain some concepts, tools, or processes.

Examples would be useful programs, and most tutorials would end with a link to at least one example. They would have some plain-text explanation of how they work, but would simply link the tutorials that thoroughly explain the fundamental concepts they depend on.

Some examples: There would be a tutorial, intermediate if not advanced, on creating custom terminal redirect objects. The tutorial would list as prerequisites the basic tutorial(s) which cover all the standard terminal functions, what they do and how they are used, as well as perhaps tutorials on tables and functions, if we cover lua language features, or simply link to the relevant chapters of the Lua PIL. Taking understanding of those as given, it would focus on demonstrating how to construct a valid redirect object, talk about the pitfalls involved in testing those redirects (errors in redirects can be tricky to debug, as errors may not display and the computer may be left in an unusable state or even force-rebooted), and walk through the creation of a redirect object of some kind - perhaps one that uses an internal buffer and draws to only part of the screen. It would not actually build a proper program using that redirect, though, just the redirect object and enough code to test and demonstrate that the redirect works.

That redirect tutorial could then link to several advanced examples that use redirect buffers - a simple chat program, perhaps a gui system, a program that allows simultaneously redirecting to multiple monitors at the same time. Each of those in turn might list as prerequisites tutorials on other topics besides redirects; the chat program would require the modem/frequencies tutorial, while the multi-monitor redirect would require the monitors tutorial.

The tutorials would be able to focus on specific concepts and features, without having to complicate things by producing a useful program, while example programs will be free to be useful without trying to have a simple, "clean" position within the prerequisite tree of the tutorials. This separation would also make it take less work in putting together the programs; it is far easier to make a well-commented example program than a full step-by-step tutorial, and with a robust and clearly-defined progression of tutorials to reference in those example programs to teach the basic concepts, example programs are freed up to focus on being good examples of useful code rather than on re-teaching the same fundamentals covered in other example programs with similar feature dependencies.

This also, I think, would be beneficial for people learning. Those who want to start from the basics and learn can follow the tutorial tree from branch to branch, learning the concepts in a logical order, building up their knowledge. The more impatient people, or those with a bit more experience, can skip straight to the examples and, if they encounter things they don't understand, easily know exactly which tutorials to read to get a handle on those things.

Tutorials would progress from basic to advanced, largely based on the amount of dependencies they have; basic tutorials would be few, and should have almost no dependencies (though there would likely be a handful of "foundation" tutorials that every tutorial depends on, covering the absolute basics like using the shell, editing programs in or out of game, the basics of the lua language, etc). Regardless of level, though, each tutorial would either explicitly explain, or link to an earlier tutorial that explains, every concept involved in the code snippets they include.

Examples, on the other hand, could have different logic. For an example program to qualify as basic, it would have to use a limited number of different concepts, and would need to be very well commented, clear, and conform to very high standards for code quality, while putting accessibility over optimization. Basic programs should avoid heavy use of non-intuitive things like the lua "A and B or C" pseudo-ternary operator, elaborate metatable and function environment manipulations, and other things that are not obvious to an amateur and could make the programs more difficult for them to understand. Advanced examples, on the other hand, could assume the reader has a good grasp of the basics. Their commenting might be more limited, focused specifically on clarifying some interaction between techniques, and deobfuscating the trickier bits of the program. They would still need to hold to a high quality for the code, but could favor efficiency and optimization over accessibility. To put it more succinctly, basic tutorials would be specially-written to be simple and easy to follow and understand, while almost any well-written, decently-commented program in the programs section could be an advanced example with only the addition of a list of prerequisite tutorials.

tl;dr: tutorials spoon-feed concepts, covering them thoroughly from top to bottom, not necessarily taking the time to deliver useful programs in the process; examples simply link back to relevant tutorials and demonstrate the ways to apply those concepts in practical programs.

#34 Lyqyd

    Lua Liquidator

  • Moderators
  • 8,465 posts

Posted 05 August 2013 - 03:23 PM

I have read through your entire post and agree to a large degree. I'll take a look at re-structuring the tutorial tree to change out some of the primarily-example-based tutorials. It would be great to get a list (or a few lists!) of example pieces, rated as basic, intermediate, or advanced, if anyone is interested in coming up with ideas on that front.

#35 Sora Firestorm

  • Members
  • 89 posts

Posted 09 August 2013 - 04:45 AM

I'm not sure how relevant this is, but I remembered I had written a tutorial on creating look-up tables (as opposed to doing the ever ugly if-elseif-elseif-else method)
Here it is unedited from its original post location. I'm pretty sure it'll need a little bit of TLC before it's usable, but here it is.

Spoiler


#36 AgentE382

  • Members
  • 119 posts

Posted 09 August 2013 - 06:05 PM

A lot of this sounds really awesome.

I'd like to contribute something that details the differences between pure Lua 5.1, CC-Lua, and pure Lua 5.2. If possible, I'd also like to write some tutorials on algorithms, efficiency, optimization, and porting other Lua scripts to CC.

I'm also capable of writing tutorials on whatever the community needs at the moment.


Ideas:
  • Convert the "Ask a Pro" section to a ticket/question-based system. (Think GitHub for tickets / StackOverflow for questions.)
  • Integrate some form of "Lua Expert" certification, maybe with different levels and specializations. (Completely independent, but would work well with the above.)
Anyway, those ideas may be completely useless, but (as stated above) I'm willing to help write tutorials :D.

#37 Bubba

    Use Code Tags!

  • Moderators
  • 1,142 posts
  • LocationRHIT

Posted 09 August 2013 - 06:26 PM

View PostAgentE382, on 09 August 2013 - 06:05 PM, said:

A lot of this sounds really awesome.

I'd like to contribute something that details the differences between pure Lua 5.1, CC-Lua, and pure Lua 5.2. If possible, I'd also like to write some tutorials on algorithms, efficiency, optimization, and porting other Lua scripts to CC.

I'm also capable of writing tutorials on whatever the community needs at the moment.

Sounds great! We don't have as many advanced Lua/programming tutorials as I would like to have, so more is always awesome.

Quote

Convert the "Ask a Pro" section to a ticket/question-based system. (Think GitHub for tickets / StackOverflow for questions.)

Unfortunately, I think this would be rather difficult for a few reasons:
1) The quality of answers may differ from person to person, and having AaP in a forum-type setting is much better at current than assigning different users to answer questions.
2) We are all volunteering limited time rather than as a job, and delay between question and response could and would become an issue.

Quote

Integrate some form of "Lua Expert" certification, maybe with different levels and specializations. (Completely independent, but would work well with the above.)

This actually was almost done towards the beginning of the forums, however the idea was dropped (there was a post about it somewhere, but I can't be bothered to find it). IIRC, it was due to the fact that we don't want good answers to be ignored simply because the person who answers has a low post count. The forum software could also have had something to do with it, though I'm not sure on that count.

Anyway, thanks for the input and I'm looking forward to your tutorials!

#38 Sora Firestorm

  • Members
  • 89 posts

Posted 09 August 2013 - 07:32 PM

I'm of the mindset that having some sort of certification would be a good idea, but how would we determine who got it?
The problem is that the easiest method of 'just counting posts' assumes that people that have 250+ whatever posts have a clue, and that people 100- don't, which isn't a reasonable assumption, at least for thinking sub-100 doesn't have a clue. The other option I can think of is 'moderator-approved' but that would quickly bog the moderators down... Why can't this be easy? :P

I'm also game for writing Intermediate+ tutorials. (as I don't take care enough to make my code 'super easy') I'm just not sure what to write about, so a list of things that would be helpful to have tutorials on would be helpful to me. :)

#39 Lyqyd

    Lua Liquidator

  • Moderators
  • 8,465 posts

Posted 10 August 2013 - 03:52 PM

The "Lua Pro" thing was done before, but was dropped due to the lack of useful objective measures for determining who is and is not deserving of the title.

For those wanting to write tutorials, there is a list of desired tutorials in a spoiler earlier in the topic, perhaps even the first post. Working drafts on any of those would be great, and it would probably be easiest to start with the most basic tutorials. The idea there is to have a set of high-quality tutorials to cover all of the basic elements of ComputerCraft, and later tutorials to put it all together and give practical examples of its use. Also read Gopher's post a few posts up if you're leaning toward writing one of the "example" or "reimplementation" tutorials.

#40 Engineer

  • Members
  • 1,378 posts
  • LocationThe Netherlands

Posted 11 August 2013 - 12:54 AM

I actually made a tutorial with the goal of this in thoughts. It probably isnt perfect, but hey, its something :)
http://www.computerc...3-event-basics/





1 user(s) are reading this topic

0 members, 1 guests, 0 anonymous users