diff --git a/sample-code/java/src/AndroidBasicInteractionsTest.java b/sample-code/java/src/AndroidBasicInteractionsTest.java
index 510d9a6ed..6814009fb 100644
--- a/sample-code/java/src/AndroidBasicInteractionsTest.java
+++ b/sample-code/java/src/AndroidBasicInteractionsTest.java
@@ -26,14 +26,65 @@ public class AndroidBasicInteractionsTest extends BaseTest {
         File appDir = new File(classpathRoot, "../apps");
         File app = new File(appDir.getCanonicalPath(), "ApiDemos-debug.apk");
         DesiredCapabilities capabilities = new DesiredCapabilities();
-        capabilities.setCapability("deviceName", "Android Emulator");
+        /*
+        'deviceName' capability only affects device selection if you run the test in a cloud
+        environment. It has no effect if the test is executed on a local machine.
+        */
+        // capabilities.setCapability("deviceName", "Android Emulator");
+
+        /*
+        It makes sense to set device udid if there are multiple devices/emulators
+        connected to the local machine. Run `adb devices -l` to check which devices
+        are online and what are their identifiers.
+        If only one device is connected then this capability might be omitted
+        */
+        // capabilities.setCapability("udid", "ABCD123456789");
+
+        /*
+        It is recommended to set a full path to the app being tested.
+        Appium for Android supports application .apk and .apks bundles.
+        If this capability is not set then your test starts on Dashboard view.
+        It is also possible to provide an URL where the app is located.
+        */
         capabilities.setCapability("app", app.getAbsolutePath());
+
+        /*
+        By default Appium tries to autodetect the main application activity,
+        but if you app's very first activity is not the main one then
+        it is necessary to provide its name explicitly. Check
+        https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/android/activity-startup.md
+        for more details on activities selection topic.
+        */
+        // capabilities.setCapability("appActivity", "com.myapp.SplashActivity"));
+        // capabilities.setCapability("appPackage", "com.myapp"));
+        // capabilities.setCapability("appWaitActivity", "com.myapp.MainActivity"));
+
+        /*
+        Appium for Android supports multiple automation backends, where
+        each of them has its own pros and cons. The default one is UIAutomator2.
+        */
+        // capabilities.setCapability("automationName", "UIAutomator2");
+        // capabilities.setCapability("automationName", "Espresso");
+
+        /*
+        There are much more capabilities and driver settings, that allow
+        you to customize and tune your test to achieve the best automation
+        experience. Read http://appium.io/docs/en/writing-running-appium/caps/
+        and http://appium.io/docs/en/advanced-concepts/settings/
+        for more details.
+
+        Feel free to visit our forum at https://discuss.appium.io/
+        if you have more questions.
+        */
+
         driver = new AndroidDriver<WebElement>(getServiceUrl(), capabilities);
     }
 
     @AfterClass
     public void tearDown() {
-        driver.quit();
+        if (driver != null) {
+            driver.quit();
+        }
     }
 
 
diff --git a/sample-code/java/src/BaseTest.java b/sample-code/java/src/BaseTest.java
index 0869df8af..c9c052c3d 100644
--- a/sample-code/java/src/BaseTest.java
+++ b/sample-code/java/src/BaseTest.java
@@ -17,7 +17,9 @@ public abstract class BaseTest {
 
     @AfterSuite
     public void globalTearDown () {
-        service.stop();
+        if (service != null) {
+            service.stop();
+        }
     }
 
     public URL getServiceUrl () {
diff --git a/sample-code/java/src/IOSBasicInteractionsTest.java b/sample-code/java/src/IOSBasicInteractionsTest.java
index e4d3556a0..5d8487bac 100644
--- a/sample-code/java/src/IOSBasicInteractionsTest.java
+++ b/sample-code/java/src/IOSBasicInteractionsTest.java
@@ -23,16 +23,74 @@ public class IOSBasicInteractionsTest extends BaseTest {
         String deviceName = System.getenv("IOS_DEVICE_NAME");
         String platformVersion = System.getenv("IOS_PLATFORM_VERSION");
         DesiredCapabilities capabilities = new DesiredCapabilities();
+        /*
+        'deviceName' capability only affects device selection if you run the test in a cloud
+        environment or your run your test on a Simulator device. This combination of this value
+        plus `platformVersion` capability value
+        is used to select a proper Simulator if it already exists. Use `xcrun simctl list` command
+        to list available Simulator devices.
+        */
         capabilities.setCapability("deviceName", deviceName == null ? "iPhone 6s" : deviceName);
+
+        /*
+        udid value must be set if you run your test on a real iOS device.
+        The udid of your real device could be retrieved from Xcode->Windows->Devices and Simulators
+        dialog.
+        Usually, it is not enough to simply provide udid itself in order to automate apps
+        on real iOS devices. You must also verify the target device is included into
+        your Apple developer profile and the WebDriverAgent is signed with a proper signature.
+        Refer https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md
+        for more details.
+        */
+        // capabilities.setCapability("udid", "ABCD123456789");
+
+        /*
+        Platform version is required to be set. Only the major and minor version numbers have effect.
+        Check `xcrun simctl list` to see which platform versions are available if the test is going
+        to run on a Simulator.
+        */
         capabilities.setCapability("platformVersion", platformVersion == null ? "11.1" : platformVersion);
+
+        /*
+        It is recommended to set a full path to the app being tested.
+        Appium for iOS supports .app and .ipa application bundles.
+        It is also possible to pass zipped .app packages (they will be extracted automatically).
+
+        Make sure the application is built for correct architecture (either
+        real device or Simulator) before running your tests, as there are not interchangeable.
+        If the test is going to run on a real device then make sure your app
+        is signed with correct development signature (as described in the above
+        Real Device Config document)
+
+        If this capability is not set then your test starts on Springboard view.
+        It is also possible to provide an URL where the app is located.
+        */
         capabilities.setCapability("app", app.getAbsolutePath());
+
+        /*
+        This is the only supported automation backend for iOS
+        */
         capabilities.setCapability("automationName", "XCUITest");
+
+        /*
+        There are much more capabilities and driver settings, that allow
+        you to customize and tune your test to achieve the best automation
+        experience. Read http://appium.io/docs/en/writing-running-appium/caps/
+        and http://appium.io/docs/en/advanced-concepts/settings/
+        for more details.
+
+        Feel free to visit our forum at https://discuss.appium.io/
+        if you have more questions.
+        */
+
         driver = new IOSDriver<WebElement>(getServiceUrl(), capabilities);
     }
 
     @AfterTest
     public void tearDown() {
-        driver.quit();
+        if (driver != null) {
+            driver.quit();
+        }
     }
 
     @Test