Java Reference
In-Depth Information
Friendly Code
When you're writing code to share with others—which means sharing with the whole
world—you need to make a little extra effort to write “friendly” code:
•Neatness counts. Put braces where they belong; don't try and jam everything on
one line or use inconsistent indentations. The format of the code can be as
important as the code itself for human readers.
•Keep it tight. Don't make lines or functions hugely long.
•Comment your functions. Explain
why
a function is there, and
what
it's used
for. Don't comment on
how
it does it—that's what the code is for.
•Honor naming conventions. Java prefers camel-case identifiers (like in the word
camelCase
), with embedded capital letters. Other languages may use names with
underscores or other conventions. Name variables so that readers can easily
understand what they are used for. Although single-letter variables (like
i
) are
often used for loop counters, that's not very descriptive. But it's even worse to
use
i
(which is normally an index) as a string or a
Location
! Stick to the conventions.
Share Code
Distributing code via GitHub is a very popular way of sharing your code with
the world. All you need to do is give out your GitHub project URL (in this
example, https://github.com/andyhunt/minecraft.git). Now anyone in the
world can use
gitclone
to get a copy of your code, and they can make their own
changes, compile it, install it, and so on.
One of the advantages of releasing your source code to the world is that other
programmers can help add features and fix bugs.
Both GitHub and Bitbucket have nice web interfaces to help with that.
Suppose one of your fans has code for a new feature she'd like you to include
in your plugin. She'd fork (make a copy of) your repository and make the
proposed changes in a named branch in her repository. Then through the
magic of GitHub (or Bitbucket), she'd submit the changes in that branch to
you as a
pull request
. That is, she's sending you a request to pull her branch
into your repository and use it.
In the web interface, you can reply to pull requests with questions and com-
ments, and have a whole discussion about the changes. If and when you want
to incorporate them, just click the Merge Pull Request button. If the new code
can merge in without any conflicts, you're done. Otherwise, click the Command
Line button, and you'll get further instructions.
