diff --git a/org.eclipse.xtend.performance.tests/src/org/eclipse/xtend/ide/tests/performance/PerformanceTest.java b/org.eclipse.xtend.performance.tests/src/org/eclipse/xtend/ide/tests/performance/PerformanceTest.java
index 1e8f03d824b..db2a8af5328 100644
--- a/org.eclipse.xtend.performance.tests/src/org/eclipse/xtend/ide/tests/performance/PerformanceTest.java
+++ b/org.eclipse.xtend.performance.tests/src/org/eclipse/xtend/ide/tests/performance/PerformanceTest.java
@@ -298,6 +298,14 @@ public class PerformanceTest extends AbstractXtendUITestCase {
 	
 	@BeforeClass
 	public static void setUpProject() throws Exception {
+		// This shadows org.eclipse.xtend.ide.tests.AbstractXtendUITestCase.setUpProject()
+		// see https://junit.org/junit4/javadoc/latest/org/junit/BeforeClass.html
+		// The class passed to TargetPlatformUtil.setTargetPlatform must be in the same bundle
+		// of the running test, while AbstractXtendUITestCase is in another bundle.
+		// Manually setting the TP allows the Tycho build to succeed
+		// otherwise, the required bundles taken from the workspace
+		// have a wrong layout in "Plug-in Dependencies", and their
+		// classes cannot be resolved
 		TargetPlatformUtil.setTargetPlatform(PerformanceTest.class);
 		IResourcesSetupUtil.cleanWorkspace();
 		WorkbenchTestHelper.createPluginProject(WorkbenchTestHelper.TESTPROJECT_NAME);
diff --git a/org.eclipse.xtend.performance.tests/src/org/eclipse/xtend/performance/tests/PerformanceTest.java b/org.eclipse.xtend.performance.tests/src/org/eclipse/xtend/performance/tests/PerformanceTest.java
index 4bcde9451c5..f9c89a6ad22 100644
--- a/org.eclipse.xtend.performance.tests/src/org/eclipse/xtend/performance/tests/PerformanceTest.java
+++ b/org.eclipse.xtend.performance.tests/src/org/eclipse/xtend/performance/tests/PerformanceTest.java
@@ -40,7 +40,11 @@ public class PerformanceTest extends AbstractXtendUITestCase {
 
 	@BeforeClass
 	public static void createTestProject() throws Exception {
-		// manually setting the TP allows the Tycho build to succeed
+		// This shadows org.eclipse.xtend.ide.tests.AbstractXtendUITestCase.setUpProject()
+		// see https://junit.org/junit4/javadoc/latest/org/junit/BeforeClass.html
+		// The class passed to TargetPlatformUtil.setTargetPlatform must be in the same bundle
+		// of the running test, while AbstractXtendUITestCase is in another bundle.
+		// Manually setting the TP allows the Tycho build to succeed
 		// otherwise, the required bundles taken from the workspace
 		// have a wrong layout in "Plug-in Dependencies", and their
 		// classes cannot be resolved
diff --git a/org.eclipse.xtext.ui.testing/src/org/eclipse/xtext/ui/testing/util/TargetPlatformUtil.java b/org.eclipse.xtext.ui.testing/src/org/eclipse/xtext/ui/testing/util/TargetPlatformUtil.java
index 3ec5207bb34..b9ecad129b2 100644
--- a/org.eclipse.xtext.ui.testing/src/org/eclipse/xtext/ui/testing/util/TargetPlatformUtil.java
+++ b/org.eclipse.xtext.ui.testing/src/org/eclipse/xtext/ui/testing/util/TargetPlatformUtil.java
@@ -43,7 +43,9 @@ public static void setTargetPlatform() throws Exception {
 	
 	/**
 	 * Sets the target platform for tests (to be used in tycho mainly)
-	 * @param context any class of the test bundle to be able to determine the test bundle
+	 * @param context any class of the test bundle to be able to determine the test bundle;
+	 * the class must be in the same bundle of the test to execute; if the class is in a required
+	 * bundle it will not work.
 	 * @since 2.14
 	 */
 	public static void setTargetPlatform(Class<?> context) throws Exception {