[michael2572]

To all plugin developers... first off, thank you very much for what you do. I speak for everyone when I say that your efforts make our servers 100 times more awesome. Right on, guys.

However, what good is an incredible plugin if nobody knows how to use it? I thought I'd take a minute to politely ask of all of you to please, please, please completely DOCUMENT your code! Most plugin threads do come with the command list, but most of them are very incomplete.

As users of your plugin, we need to know not only the command & its parameters, but also the return values. What does the function do when certain conditions are met? And also we would absolutely love an example or two. Here, let me show you what I mean:

• command_one(required_param, [optional_param = 0])
  Does this and this and with certain players, and has a lot of fun. Yay.
  Returns: 1 on success, 0 on failure.
  Example:
  
  pawn Code:

  if (command_one(blargh)) // we add a comment and explain something that the viewer might not understand so easily.
       print("Yes");
  else
       print("No");

• command_two(another_cool_param[])
  Accepts this awesome string and does some awesome things with it, then returns it.
  Returns: The modified string. If this condition is true, then it returns a different value which is ____.
  Example:
  
  pawn Code:

  new somevar[64]; // another important thing here is...
  GetPlayerSomething(playerid, somevar);
  format(somevar, 64 "Bla bla bla %s bla bla", command_two(somevar)); // be careful when...

  Since this command is super useful and you can use it in different ways, I will show you an example of doing things a slightly different way...
  
  pawn Code:

  new somevar[64];
  // (code)

...And so on. Notice how formatting makes it very easy to read. Make use of [pawn] tags and [b] bolding within each

• list item. Make your work shine!
  
  If you are a plugin author, you know exactly what your code does. It would be fabulous if you could spend some time making it easy for the rest of us to know, too. It saves us from plenty of unnecessary guessing and checking and debugging. Thank you!

[michael2572]

Well, looks like this one's goin' blub blub blub...