Before you post, read this.

Started by Vanguard, April 04, 2016, 11:55:41 AM

Previous topic - Next topic

Vanguard

Hello, proud CRPeople. I am reluctant to post this, as there are a lot more people with a lot more experience than me, however, in order to save us all some time and set a few helpful standards new coders can aspire to, I want to share this post with you and request to make it sticky. The goal is to have a common and helpful set of rules when it comes to discussing coding in CRPL. Please, post any helpful additions that you´d think should be in here or disagree with it as you see fit.

Before you post, read this

Before submitting your post to the community, please take your time to follow these few simple guidelines that will save you time and will allow us to help you in the first place. Creating a proper topic for discussion will help you get an answer faster.

1) State your idea or Problem clearly

This is the most important part. Sometimes you have an awesome idea, but don´t know how to do it best. Stating your idea in detail will allow others to find the optimal solution, which may even be better than the original solution you tried. This will also help us to fact check your idea, which may have a logic error in the first place. Explaining your idea so that others understand it properly is really important.
   
Good Example:

I want to make an unit, which can soak up AC and spit it out at another location. This are the things the units need to be able to do:
   
   1) Soak up AC ( cannot be cancelled, so no need for controls )
   2) Stationary ( no Movement controls needed )
   3) Select a location to drop the collect AC in regular intervals ( button controls needed )
   
Here is my take at the solution ( include code example if you already have code, otherwise just state your idea ).
   

Bad example:

Hi guys. Here is my unit and it´s not working ( code example attached without debugging or more information on what´s not working )

Good example:

Hi guys. This is my unit ( code example with debugging and inline comments ). It´s not working, because it does not do X, when I try to do Y.


Remember that proper formating ( linebreaks, code tags for code, spoiler tags for spoilers, thought dashes, etc. ) will make it easier for us to understand your problem. Nobody likes to read a wall of text AND deal with a complex problem at the same time.

If you are simply asking what´s possible with CRPL, also make sure you get your idea across as clearly as possible. Second guessing your intentions when you are unclear about the purpose is unproductive.

2) Break down your problems into smaller ones

Any task can usually be reduced to smaller, simpler steps. Let´s say you want to make an unit. This may look like an overwhelming task at first, however breaking it down, it will look less intimidating. Breaking problems down will also help you to improve your design.

Example

I want to have an unit that does awesome stuff with creeper! It can jump around the map, create creeper, place digitalis and teleport!

How do I do this best? Hmm, let´s think about what the unit needs to be able to do.
   
1) Move. When should it move? Where should it move?
1.1) I´d like it to move, when a certain amount of creeper is acquired at it´s current location.
1.2) It should never go near any command node or a certain area of the map.
2) Teleport. Hmm, it´s just another form of movement.
2.1) Maybe I will not implement any movement code at all and simply update it´s position on a teleport.
2.2) I want cool effects to be played when it teleports. Maybe even sound.
3) Create creeper. How much? Interval?
4) place digitalis. When? Where?
5) Adding more questions to the to do list, like "can it be neutralized?" or "can it be taken down by a sniper?". Should it count for victory conditions and more.


You see, a simple ordered list of things to do will already make your design and implementation that much easier than simply start coding away. It will also help us to understand better which part of the idea/code is broken and needs fixing.

3) Always keep the reference in mind

https://knucklecracker.com/wiki/doku.php?id=crpl:crplreference

People post incredibly useful stuff in the wiki. Maybe your exact problem is already detailed there.

4) CRPL examples can help you understand the code better

There are already a few examples which can be used to look at how people solved different kinds of problems. Take a look at them if you like.
   
http://knucklecracker.com/forums/index.php?topic=12255.0
http://knucklecracker.com/wiki/doku.php?id=crpl:crpltutorial:code_examples

5) Use tracing and debugging

There are a few of simple to use yet incredibly useful tools which will usually even help you solve the problem yourself in the first place. If you are looking into help with your code, it is highly recommended to familiarize yourself with these babies.

https://knucklecracker.com/wiki/doku.php?id=crpl:docs:showtracelog
https://knucklecracker.com/wiki/doku.php?id=crpl:docs:trace

These are your basic tracing tools to show what is going on with your CRPL core.

https://knucklecracker.com/wiki/doku.php?id=crpl:docs:tracestack

Again, a bit of tracing. This will show you certain steps of calculations you are processing.

Posting trace output to the forums will narrow your problems down very quickly, even if you yourself might not understand them fully.

The most basic methods of debugging look like this:


# Lines prefixed with a hashtag are comments and will not execute, so have as many comments as you like. :)
once
# Activating a debug output
ShowTraceLog
endonce

Trace("This code will be executed every frame.")

# I want this line to show only if I am in the editor mode
# https://knucklecracker.com/wiki/doku.php?id=crpl:docs:iseditmode
iseditmode TRUE eq if
Trace("I am in editor mode. This part of the trace will not show up in the finalized version. Very helpful for when you do not want to rewrite your code when you are done.")
endif


6) Try to include links to the CRPL reference when you debate on functions or custom code

This is basically just a courtesy for your fellow mammals and will show us that you looked at the CRPL reference itself in an effort to solve the problem and it will make it abundantly clear that we are all talking about the same function(s).

Lastly: Don´t be afraid to post, even if you feel you are not really sure what your problem or idea is. KC Forums are a helpful and productive place. These are just basic suggestions to help us all, not mandatory requirements.
   
Thanks for taking your time to read this and I hope you found it helpful. Please let me know if you think I missed a point.

Addendum: Potentially helpful topics
Mini Tutorial on tracing ( Author Goodmorning in http://knucklecracker.com/forums/index.php?topic=20466.0 )
Spoiler
The quick tutorial on Tracing:

1. When debugging, if the code doesn't work perfectly the first time (i.e. always) then you will almost certainly want to use Trace.
2. To see the trace window, run the command ShowTraceLog.

3. Depending on the nature of the bug/s, different tracing functions can help.
3.a. Trace, Trace2, Trace3, and Trace4 will consume that many stack arguments, and trace their values.
A good example of this is the following: "TargetCoords" <-TargetX <-TargetY Trace3
This will leave the stack unchanged, but show you what is going on.

3.b. TraceStack is good when something strange is going on, and things aren't ending up where they should.
TraceStack won't change the stack, only show it. Be warned: this rapidly fills the trace history if you call it often. It can be hard to find something specific, but will give you an overview.

4. If the trace window fills up, and you are looking for something specific, it may be time to use ClearTraceLog, which will clear the trace window. This can be very useful.

5. A command that can be helpful if you have a rare condition that happens quickly, (e.g. the Core finishes charging) you may want to pause, so that you can see the trace from that point.
This can be achieved by: <-SomethingBadlyWrong if
  ShowTracelog
  TraceStack
  PauseGame
  1 Delay
endif


6. If you have managed to fix whatever was wrong, you may want to hide the trace window, instead of the quick-and-dirty make-a-new-Core solution, the you will need HideTraceLog.

7. At some point, you will probably see a message "WARNING: Trying to take item from an empty stack". This is an easy error to make, but one that's infinitely easier to fix with the aid of the trace.

There is little more that can be taught, it's largely a matter of intuition. With practice you can start to guess what is going wrong, or at least where to put the Trace statements. Common places are just before "if"s, at the start, and around function calls.
[close]