Just some bits of general documentation.
- Google Apps for e-mail, calendar, docs, and video-conferencing (via Hangouts)
- git for version control
- GitHub as the git repository
- Slack for team communication
- Trello for task management
- Eclipse ADT as the IDE for projects created before August 2014
- Android Studio as the IDE for projects created in August 2014 or later
- Crashlytics for crash reporting
- Flurry for detailed analytics
- Localytics for analytics with better segmentation capabilities
- Google Analytics for high-level analytics
- Jenkins for the continuous build, hosted at CloudBees
- Hockey App to circulate alpha and beta versions
Other tools we recommend using (for Mac):
- Homebrew for software package management
- iTerm2 as a better terminal
- Sublime for a good text editor. Also, check this guide to use it from your terminal
- Skitch to quickly take and edit screenshots
- LastPass for password management
- SizeUp, a great window manager
Our git workflow
If you're new to Git... good luck! There's a lot of information out there. Spend some time experimenting with the main commands in this playground.
A note about commit messages
A commit is a logically separate changeset. It is not a bunch of unrelated changes that you're sending to the repository for backup. For instance, you just fixed a bug (so, your commit message would read something like Fixed crash on startup for images larger than 5MBs), implemented a few feature (e.g. Added support for animated GIFs), did some internal change (e.g. Moved the video editing logic out of the full-view activity). It can also be an intermediate step towards a big feature, but it needs to be easy to describe and self-contained. If you need to use the word and, it usually means you're doing it wrong.
As for Git-specific guidelines, see the first sections of Git's contribution guidelines.
Java code style
We follow Google's style guide. The only notable exception is the column limit: we ues 120 characters (not 80 or 100). Screens are wide enough nowadays.
But, above all others, consistency is the most important rule: follow the conventions of the file you're working on.
Java/Android programming conventions
We agree on the conventions laid out in iwombat's Guidelines. The only (minor) inconsistency with our code style is the blank line they leave after class and method javadoc comments: we follow the official javadoc recommendation and omit it.
Also, iwombat's Exception Standards are a good read on good practices for exception handling.
The Android Developers site also has a small set of guidelines: Code Style Guidelines for Contributors. We follow it except for the naming conventions for fields: we stick to general Java's guidelines and do not prepend fields with m or s. And, again, the 120 column limit.
Java code formatting
If you use Eclipse, go to Window -> Preferences → Java → Code Style → Formatters, and then import this XML file. If you use IntelliJ, well, you’re on your own!
Again, remember that, in any case, the most important rule is to be consistent with the existing style of the project/file you're working on.
Can't recommend Effective Java enough. If you haven't, just go ahead and study it now.
Head First Design Patterns
Head First Design Patterns is probably the best introductory book about design patterns. Definitely a must.
While you're here, set aside some time and watch the Clean Code Talks by Misko Hevery. It's just genious.
Proper naming is essential to make code understandable to others.
The most important check for a proper name for any element is: when you have to describe that element, do you use the words in its name? If you don't, the name of that package/class/method/variable/constant is most likely wrong.
Class names are always nouns. For instance,
Interfaces names are usually adjectives, such as
Clonable. They are also use to define the public operations of domain objects, so nouns are acceptable
Method names are always verbs, such as
Variable names usually take their name from their type, such as
Read the section on Naming Conventions from this University's Style Guide.
How to clone and configure your workspace in Eclipse
The basic steps are the following:
- Clone the repo:
git clone email@example.com:androidsx/PROJECT.git
- Open Eclipse and set the
PROJECTfolder as the root directory for the workspace
- Import all projects from the
PROJECTfolder: File -> Import -> Existing Projects into Workspace
However, if you already have an Eclipse workspace with a nice config you like (shortcuts, templates, fonts, etc), use this script, renamed to
new-workspace.sh below, to copy it into our new workspace:
./new-workspace.sh $EXISTING_WORKSPACE $NEW_WORKSPACE
You can now do the following trick to clone into this folder (based on this answer on stack overflow):
git clone --no-checkout $REPO $NEW_WORKSPACE/tmp mv $NEW_WORKSPACE/tmp/.git/ $NEW_WORKSPACE/ rmdir $NEW_WORKSPACE/tmp/ cd $NEW_WORKSPACE/ git reset --hard HEAD
These instructions are copy-pasteable into your terminal if you just assign your own values to the variables:
EXISTING_WORKSPACE=chat-toolkit NEW_WORKSPACE=lottodroid REPOfirstname.lastname@example.org:androidsx/lottodroid.git
How to remove folders and its history from Git
First, take this script in GitHub's wikie and save it as "git-delete-history".
Let's copy and clean the repository:
ツ ~/workspaces$ cp -rf sx-git/ sx-git-pruned/ ツ ~/workspaces$ cd sx-git-pruned/ ツ (master) ~/workspaces/sx-git-pruned$ git clean -xdf ツ (master) ~/workspaces/sx-git-pruned$ find ./first-folder-to-delete ./second-folder-to-delete -name \* -print
Apply the magic:
ツ (master) ~/workspaces/sx-git-pruned$ find ./first-folder-to-delete ./second-folder-to-delete -name \* -print | xargs ../git-delete-history
Now push to a newly created repo:
ツ (master) ~/workspaces/sx-git-pruned$ git remote rm origin ツ (master) ~/workspaces/sx-git-pruned$ git remote add origin email@example.com:androidsx/chat-toolkit.git ツ (master) ~/workspaces/sx-git-pruned$ git push -u origin master
How to split a directory into another repository
Very simple steps outlined here.
How to create a sample animated GIF
Useful for a quick demo, like the one in https://github.com/androidsx/jog-tracker. Follow these steps:
NAMESPACE=v2 DELAY=35 for i in `seq -w 1 1 300`; do adb shell screencap -p | perl -pe 's/\x0D\x0A/\x0A/g' > $NAMESPACE-$(date +%Y%m%d-%H%M%S).png; echo -e "Took screenshot $i"; done; for i in `ls $NAMESPACE-*.png`; do convert $i -scale 50% $i.gif; done; convert -delay $DELAY -loop 0 $NAMESPACE-*.gif animated-$NAMESPACE-$DELAY.gif
- Configure git auto-completion for branch names from the command line. Download https://github.com/git/git/blob/master/contrib/completion/git-completion.bash to your HOME, and add
source ~/.git-completion.bashto your
- Configure your git configuration (aliases, syntax coloring, etc). Follow https://github.com/SixArm/sixarm_git_gitconfig for a very well-organized config
- Configure your prompt (PS1) with https://github.com/vergenzt/git-colored-ps1
Useful git scripts
Only start using these after you are fluent with Git.
git-upto sync all local branches with the remote ones
git-wtfto quickly know the status of your repo
git-publish-branchto publish local branches easily
There are other extensions that pimp out your Git commands much more, such as
hub, but we're not using them. Up to you, though.
Useful Gradle tips
How to make Gradle builds much faster in your local machine: create the file
~/.gradle/gradle.properties with these two lines (source here):
Additionally, this will speed them up noticeably in Android Studio:
- First, open Preferences -> Compiler, check "Compile independent modules in parallel"
- Then, in the box for VM Options, set
- Last, go to Preferences -> Gradle and check "Offline work" in the "Global Gradle settings" section
To have them fly in your Continuous Build, follow the simple steps in http://tools.android.com/tech-docs/new-build-system/tips#TOC-Improving-Build-Server-performance. to disable pre-dexing of libraries on your continuous build, since we're "cleaning" every time there anyway. However, this has funny consequencies if you're doing multi-dex tricks to work around the 65k method limit.
Code review tips
kdiff3as the diff/merge tool. It's ugly, but works well. Install with
brew install kdiff3and set as the default with
git config --global merge.tool kdiff3. Here's a quick guide on how to use it: http://www.gitguys.com/topics/merging-with-a-gui/
Script for poster
See the file