Attention Developers: Opportunity to contribute to Spigot / build your portfolio!

Discussion in 'Spigot Plugin Development' started by jflory7, May 8, 2015.

  1. jflory7

    Retired Benefactor

    Hey Spigoteers!

    I just wanted to share some information about a particular wiki article on the wiki, Plugin Snippets.

    This wiki article was created in the summer of 2014 but we never really went anywhere with it, but I was hoping to try to breath some life into this a little. The intention is that any user can contribute short snippets of code that might be useful for beginning developers to reference for getting started with their plugins or projects. By referencing code snippets or guides in that category, beginning users can read well-composed guides and articles that will teach good habits and provide a useful reference as they begin to dip their feet into the Spigot API.

    I know many people have written tutorials and guides in this forum already - this is an opportunity for you to place your tutorials in a place where they can be read by more eyes and you can have a dedicated area of discussion related to your contribution. Furthermore, for those of you offering services in the Services & Recruitment forum, this is also a great opportunity to expand your credibility and ability by contributing your own well-written guides for new developers.

    I just highly encourage anyone who might want to contribute to this wiki category to please have your code peer-reviewed! We only want to publish code in this category that teaches good habits and seeks to educate, not just to "give" code. Hopefully some of you take advantage of this opportunity and contribute some awesome guides!

    Let me know if you have any other questions.

    Cheers,
    - jflory7​
     
    • Like x 20
    • Winner x 3
    • Informative x 3
    • Agree x 1
    • Funny x 1
  2. Just wanted to be the first on the post.

    Glad you followed my idea for putting it in the sticky's.

    Can't wait for people to start putting their threads.

    I see one problem with this though, which is new copy-pasting.

    This is a note for all new developers:

    You should always use snippets as an example, but try and reduce the amount of copying. If you don't fully understand a snippet you should probably look back at the docs or check it around.

    Otherwise this is a great idea for optimisation of code, and much more!

    Thank you spigot!

    -DiamondBurner
     
  3. jflory7

    Retired Benefactor

    Yeah, what should be emphasized with this is teaching, not just "giving" code. Explaining what certain API calls do, how x affects y, etc. is important. Anything contributed to the wiki should keep this mind, as its intention should be to teach and educate.
     
    • Agree Agree x 4
  4. Maybe minimize the "snippet" size will be good. Try to demonstrate the most important part.
     
    • Agree Agree x 1
  5. uh, speaking of teaching instead of giving: http://www.spigotmc.org/wiki/recipe-example/
    It doesn't explain much of anything at all..
     
  6. jflory7

    Retired Benefactor

    That was one of the original contributions from 2014. You're more than welcome to tackle that one and add on to it, and make it more like a lesson than just a "gimme". We hadn't really established the section yet when that contribution was made.
     
  7. gigosaurus

    Supporter

    Perhaps a guideline that the larger snippets should be more of demonstrating how something should be done rather than copy&paste&compilable.
     
  8. I have one question which is, how is the format supposed to be. I have two different ideas on how it should be.

    Either like this:

    Now let's create the diamond sword!
    Code (Text):
    ItemStack diamond_sword = new ItemStack(Material.DIAMOND_SWORD);
    Or do we have to everything in the code:

    Code (Text):
    //Now let's create the diamond sword!
    ItemStack diamond_sword = new ItemStack(Material.DIAMOND_SWORD);
     
  9. gigosaurus

    Supporter

    Have a read of this, it should clarify when/what/where you should comment: http://www.cwu.edu/~gellenbe/javastyle/commenting.html
     
    • Agree Agree x 1
  10. That was not my question.

    My question is. Should everything be written inside the code or should we have texts in between them. It's not a matter of conventions it's a matter of the spigot format.
     
  11. gigosaurus

    Supporter

    Comments should just be explaining the purpose of the code. If you want to explain what you're doing or why you're doing it then you would be better off having a section of text instead of a comment.
     
    #11 gigosaurus, May 8, 2015
    Last edited: May 8, 2015
    • Agree Agree x 1
  12. I'm not sure how @jflory7 intends for it be done, but I personally think it would look better to have a section of text and then a snippet of code to follow it. This way, when a user is reading the snippet, he/she can reflect upon the previous section of text for a better understand. For example,


    On an side note, I also think it's important to link the user to the associating JavaDocs (see my example) to help them not only learn the API, but also learn how to use the JavaDocs to their advantage later on down the road.
     
  13. Awesome, I didn't know about this :)
     
  14. Awesome! I want to help out some people with tutorials and this can also help me out for when I am absolutely lost in my code hahahaha :D I have a question though, how exactly do you make a wiki article?
     
  15. That's what I thought. But now that I look at the format of the forum. It looks like a quick description and the code.

    We need @jflory7 to clarify ;).
     
  16. I honestly don't think it matters. Normally if you are trying to explain something >1 line, it would be nice to have an explanation in text. If you are trying to explain something short, comments are fine.

    At least that's my opinion.
     
  17. Create a new page using the "Create New Page" button under the Wiki button (on the header), and then set the Parent Node to "Plugin Snippets" under the Spigot parent node.
     
    • Agree Agree x 1
  18. Is there a convention to follow because this is heavily needed IMO. Formatting, and naming of classes and packages is severely un-uniform with several of these offerings. I.E. http://www.spigotmc.org/wiki/creating-a-blank-spigot-plugin-in-intellijidea/
    If there is may I suggest they're documented somewhere.

    As well as a sample plugin package and sample plugin class to make different snippets joinable if needed.
     
    • Like Like x 1
  19. gigosaurus

    Supporter

    It really shouldn't matter as long as they follow the Java code conventions (which ironically the page you linked doesn't), and that each page is consistent throughout, e.g. you don't suddenly start placing brackets on a new line half way through when you've had them on the same line until then. Anything else is personal preference. Due to the nature of this wiki section, it doesn't matter if the pages aren't completely consistent with each other.

    IMO snippets are there to help guide beginners in the right direction, and so being able to join snippets together so that you can just copy and paste a plugin together definitely shouldn't be a feature.
     
  20. It's for people who are looking to add features without the mass knowledge of Java. Yes they can learn but just for ease they can copy, paste, and manipulate the snippets, with somewhat reasonable readability and formatting. That way if there are problems it helps us, and them.
     

Share This Page