Contract Usage and Evolution in Android Mobile Applications

An exception can be used to signal, at runtime, a contract violation. Bloch [6] suggests the use of runtime exceptions to indicate programming errors, as the great majority indicates precondition violations. However, it is important to note that the exception itself does not represent a contract; it needs to be associated with a previous check (e.g., an exception thrown inside an if-else block) to be considered so. Java and Kotlin offer many exceptions that can be used for this purpose, such as the IllegalArgumentException. The android.util package offers additional exceptions that we are also interested in analyzing, such as the case of the AndroidRuntimeException. Additionally, we are interested in a particular exception, the UnsupportedOperationException, which, according to the Java documentation, is thrown to indicate that the requested operation is not supported. As Dietrich et al. argue, this is the strongest possible precondition and can not be satisfied by any client [13].

The following code shows an example of a precondition. An IllegalArgumentException is thrown when the contract shoppingCart.isEmpty() is violated. The method proceedWithCheckout can only perform its task when the shoppingCart has at least one item.

We consider a total of 74 CREs (while Dietrich et al. [13] consider six). We show some examples in Table 1 but, due to lack of space, the full list is in the Supplementary Material [17].

APIs consist of wrappers around conditional exceptions and other basic constructs. This contributes to a simpler and explicit representation of contracts. We are interested in the four APIs listed in Table 1. For example, the Apache Commons offers the Validate⁷⁷7https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/Validate.html (last accessed on 01 April 2025) class that, according to the official documentation, “assists in validating arguments”, suggesting a precondition usage. The methods provided by the Validate class are simply wrapping exceptions that we have already considered in the CREs. The same libraries do not offer any equal approach to specify postconditions, which suggests a preference from tool builders towards preconditions. Nevertheless, and against the guidelines, practitioners can still use any of those API’s methods to check postconditions.

In the following example, that makes use of an API, a precondition items list is not empty is declared. In other words, the method addToShoppingCart guarantees that if the client fulfills its obligation to provide a non-empty list of items, it will be able to perform its job correctly.

Assertions were introduced in Java 1.4 and are specified through the assert reserved keyword. It helps practitioners verify conditions that must be true during runtime. JVM throws an AssertionError if the condition is false. However, JVM disables assertion validation by default, requiring it to be explicitly enabled. This means that practitioners may assume that contracts specified through assertions will be validated at runtime when in fact the assertions are disabled. This leads to an incorrect, and potentially dangerous, assumption. Having that in mind, assertions can still easily be used to check preconditions and postconditions.

In the following example, the contract associated with the addToShoppingCart method defines two preconditions – the list of items to add to the shopping cart must have a size of greater than zero and smaller or equal to ten – and a postcondition – the items added to the shopping cart will be present in the shopping cart list.

Kotlin also has its own assert. However, contrary to the Java version, assert in Kotlin is a function and not a reserved word. This means that any class can define a method with the name assert, which makes it harder for an automated analysis tool to distinguish between Kotlin’s assert or a developer’s custom method. Additionally, contrary to Java, Kotlin always executes the assert expression and only uses the -ea JVM flag to decide whether to throw the exception. Kotlin also offers other methods: check(), checkNotNull(), require(), and requireNotNull(). Although these throw an IllegalArgumentException or an IllegalStateException instead of an AssertionError, we added them to the assertions category because of their syntactic similarities.

The following code uses Kotlin’s methods to specify the same pre and postconditions as in the previous Java example.

Annotations are metadata added to the program providing information that can be used at compile time or runtime to perform further actions. Java provides many annotations through the java.lang package. Table 1 lists the annotation packages we are particularly interested in studying. No previous studies consider the android.annotation and the androidx.annotation.

The annotation-based approach is particularly interesting for two reasons. First, many annotations can be associated with the method’s arguments (preconditions), the method’s return values (postconditions), or the class properties (invariants). Second, since annotations are usually added to the method’s signature or to the class property, there is a greater separation between the contract specification and the service’s implementation. This means that annotations, like in the Eiffel’s approach, do not increase the complexity of the method’s implementation, contrary to what happens with CREs, APIs, and assertion-based approaches.

The code shown below uses annotations from the javax.validation.constraints.* packages to specify contracts. The method states that it can only return a list with a minimum size of 1 (postcondition), if the item identifier is not null and the quantity is greater or equal to one (preconditions). Also, the class property items is associated with a class invariant that states that the shopping cart can only contain ten items at maximum. This example shows that adding contracts through annotations does not require adding extra checks to the implementation, contributing to cleaner code.

We consider Kotlin Contracts⁸⁸8https://github.com/Kotlin/KEEP/blob/master/proposals/kotlin-contracts.md (last accessed on 01 April 2025), an experimental feature introduced in Kotlin 1.3 that allows developers to state a method’s behavior to the compiler explicitly. As the following example shows, they also provide useful information to the compiler: the call to split in line 4 causes no error, because the contract specified in line 10 guarantees that birthdate is not null.

It is widely supported that DbC contributes to improving software reliability [28, 39, 19]. The advantages commonly mentioned are that DbC (i) improves code understanding [16, 29, 39, 34], (ii) helps identify bugs earlier and diagnose failures [39, 4, 9, 13, 33], and (iii) contributes to better tests [39, 4, 33, 3, 36]. Some studies demonstrated that DbC requires fewer project person-to-hour resources [8, 36], but could not confirm an impact on quality. Moreover, DbC contributes to less time spent on writing tests [36]. Blom et al. [7] suggest that DbC results in fewer errors and decreases development time. In another study, Zhou et al. [42] show that DbC increased reliability in software components. In a study on C# projects using Code Contracts, Schiller et al. [33] found a high percentage of contracts related to null checking and suggest the importance of creating design patterns alongside tools and libraries. Estler et al. [15] analyzed 21 Eiffel, C#, and Java projects known to be equipped with contracts. Most contracts are null checks, with preconditions being typically larger than postconditions. The authors concluded that the average number of clauses per specification is stable over time and that the method’s implementation changes more frequently than its specification. However, they warned that strengthening contracts may be more frequent than weakening, indicating some unsafe evolution of contracts. Lastly, Dietrich et al. [13] investigated 176 popular Java projects in the Maven repository and found that the majority of programs do not use contracts significantly. They found that CREs are the most commonly used category, followed by asserts. The dominance of preconditions over postconditions in contracts is consistent with other studies [10, 33]. They found that projects that use contracts maintain or even expand their usage over time. Similarly to Estler et al. [15], the authors reported some unsafe evolution of contracts, which can happen when a method strengthens its preconditions or weakens its postconditions. They also found many violations of the Liskov Substitution Principle (LSP), with prevalence in the annotations. The LSP states that objects of a superclass should be replaceable with objects of a subclass without altering the correctness of the program. According to this principle, a sub-type can only weaken preconditions or strengthen postconditions and class-invariants from its parent [1]. A sub-type should behave in a way that does not violate the expectations set by its super-type. This ensures that any code that works with the super-type can work with the sub-type without requiring modifications or encountering unexpected behavior. The authors caution that their dataset mainly includes libraries, which may explain the low usage of annotations. This study is the one most related to the work presented here, as it also studies contracts in Java. However, our study differs from Dietrich et al.’s [13] in that, not only we consider more constructs, we also focus on Android apps and we study both Java and Kotlin.

Kudrjavets et al. [22] studied two Microsoft Corporation components, written mainly in C and C++, and found that increased assert density led to a decrease in fault density, and that using asserts was more effective for fault detection than some static analysis tools. Kochhar and Lo [21] studied a dataset of 185 Apache Java projects available on GitHub and found that adding asserts contributes to fewer defects, especially when many developers are involved. This agrees with reports from Kudrjavets et al. [22] but it is not supported by Counsell et al. [12], who analyzed two industrial Java systems and found no evidence that asserts were related to the number of defects. Kochhar and Lo [21] also concluded that developers with more ownership and experience use asserts more often, which shows that more advanced programmers see it as a valuable practice. In line with other previously mentioned studies for contracts [33, 15], most uses are related to null-checking.

There is a general understanding that the use of annotations among practitioners is growing [40, 18]. Yu et al. [40] conducted a study on 1,094 GitHub open-source projects and found a median value of 1.707 annotations per project, with some developers overusing them. The authors argue the need for better training and tools to help derive better annotations. Other authors made a similar claim for contracts [33]. Additionally, developers with higher ownership use annotations more often, which agrees with the findings by Kochhar and Lo [21] related to assertion usage. Grazia and Pradel [18] investigated the evolution of type annotations, some of which can act as contracts, in 9,655 Python projects. The authors reported that although type annotations usage is increasing, less than 10% of potential elements are being annotated. This contradicts the (general) annotations overuse reported by Yu et al. [40]. More importantly, the study found that once added, 90.1% of type annotations are never updated. This indicates that specifications are more stable than implementations, which is desirable. A similar finding was reported by Estler et al. [15] related to the stability of contracts while the program evolves. Also relevant is that most type annotations were associated with parameter and return types, rather than with variable types. Finally, the authors found that adding type annotations increased the number of detected type errors. This motivates the general use of these features to improve software reliability.

In this study, we aim to answer the following research questions:

• $\mathrm{■}$

  RQ1. [Contract Usage] How and to what extent are contracts used in Android applications?

• $\mathrm{■}$

  RQ2. [First-To-Last Version Evolution] How does contract usage evolve in an application from the first to the last version?

• $\mathrm{■}$

  RQ3. [Safety] Are contracts used safely in the context of program evolution and inheritance?

The dataset used is composed of real-world apps obtained from F-droid,⁹⁹9https://f-droid.org (last accessed on 01 April 2025) an alternative app store listing over 4,000 free and open-source projects. The fact that it has a large number of open-source apps on a wide range of domains, makes F-Droid a good option. Moreover, F-Droid is normally used in research studies on Android apps [11, 41]. Apart from native Android apps written in Java or Kotlin, F-Droid’s catalog also contains projects that use hybrid frameworks (e.g., React Native) that we exclude from our dataset.

We started by downloading the F-Droid index, which is a list of URLs for each project available in the catalog. Next, this list is filtered based on the following criteria: 1) The application source code is hosted in GitHub; 2) The application source code is either Java or Kotlin; 3) The GitHub project is not archived; 4) The GitHub project has had a commit since 2018. These inclusion criteria ensure that the project’s source code is easily accessible (through GitHub), is written mainly in Java or Kotlin (the languages we are interested in studying), while also guaranteeing that the project is active and relevant. We retrieve two versions for each of the filtered projects, which is a required step for the First-to-Last Version evolution study. We do this by storing a list of the URLs pointing to two GitHub versions: we first try to retrieve the oldest and the most recent release; if there are not enough releases, we try to retrieve the oldest and the most recent tag; finally, if there are not enough tags, we just keep the most recent commit of the repository. If there are no releases nor tags, we only consider one version (excluding it from the First-to-Last Version evolution study). Although our script resolved most of the versioning schemes found, some projects required manual handling to determine which version was the first and the last. Throughout the paper we refer to the most recent version as last or second version. Finally, we clone all the projects contained in the versions list. Every file that is neither a Java nor a Kotlin file is removed from the dataset, which helps to decrease its size.

Here, we describe the analysis tool and the studies conducted to answer our research questions: the usage study, the first-to-last version evolution study, and the Liskov Substitution Principle study.

Table 4 shows the number of contracts found per category, considering all versions (columns 2 and 3) and considering only the latest version of each app (columns 4 and 5). The table also identifies the number of apps containing at least one contract for that category (columns 6 and 7). The most obvious conclusion is that, in both languages, annotation-based contracts are the most popular category. More specifically, considering both languages in the last version, annotations represent 85.2% of the contracts found, followed by CRE with 11.1%, and then assertions with 2.9%. The results show similar tendencies between Java and Kotlin, and the only difference is that while Java’s second most popular category is CREs, in Kotlin, it is assertions. This relatively high percentage of the assertion category in Kotlin is explained by our inclusion of the four language’s standard library methods listed in Section 2, where require() alone counts 901 total occurrences.

This distribution in categories’ popularity significantly differs from the findings of Dietrich et al. [13], who reported that the most common category was CREs and found surprisingly low use of annotations. This may be explained by the fact that, while our dataset is formed mostly by user-focused Android applications, Dietrich et al.’s dataset was mainly Java libraries. In Table 6, we can also see that most annotations found belong to the androidx.annotation.* package that the authors did not consider since it is Android-specific. Nevertheless, the high number of annotation-based contracts found is in line with literature that supports its increasing popularity [40, 18].

From Table 4, we also verify that the usage of APIs is low in both languages, and it is even more residual in Kotlin applications, where only nine instances were found in the latest versions. Skepticism around adding third-party dependencies to projects, which may lead to maintainability and support issues in the future, may explain this finding [5, 38].

Table 6 shows the frequency of each construct. We highlight that the high number of annotations found is leveraged mostly by the androidx.annotation.* package. In APIs, the Guava library constitutes most of the usage. We were not expecting to see any usage of Spring Framework Asserts since this library was designed to be used in the Spring framework, but we still found one occurrence. At the same time, we found no occurrences of the now deprecated FindBugs annotations. Additionally, we identified a single occurrence of Kotlin Contracts, which may depict the practitioner’s distrust of using a feature still in an experimental phase.

We now consider Table 5, which presents each category’s computed Gini coefficient. The Gini coefficient measures the inequality among the values of a frequency distribution. In other words, a Gini coefficient of 0 indicates perfect equality, where all apps have the same number of contracts. In contrast, a Gini coefficient of 1 means that a single program has all the contracts. We observe that all coefficients in the table are high, except for Kotlin’s API usage. This means that although some apps use contracts intensively, the majority does not use them significantly. This aligns with the results found by Dietrich et al. [13]. This conclusion can also be seen in Table 7, where the five projects that use more contracts per category are listed. The table shows the number of contract elements used and the application’s category. We find that a small group of projects own a large percentage of the overall use in each category. It is clearly visible from the assertion and CRE categories that the numbers quickly decrease through the first to the fifth application showing the unbalanced usage between applications. F-Droid does not provide statistics, such as downloads, but the categories shown provide an indication of their purpose (with over half of these applications belonging to the category Internet).

Lastly, Table 8 presents the frequency of each contract type. Once again, we have distinct results for Java and Kotlin. In Java, we found 64.80% of the classified instances in the last versions to be preconditions, 22.87% postconditions, and only 12.32% class invariants. These results align with other studies on contracts [10, 33, 13] that show a clear preference towards preconditions. However, results for Kotlin are different: considering last versions, we found 38.81% to be postconditions, 31.64% class invariants, and 29.55% preconditions. This suggests that Kotlin developers tend to favor postconditions, while preconditions come at the last position. According to the classification described in Section 4.3.2, only annotations are classified as postconditions or class invariants. This means that in Kotlin, there is a higher number of annotations associated with methods’ return values and class properties than with the methods’ parameters.

Although we can not provide a reason for this finding with certainty, analysing the most frequent constructs for pre and postconditions in both languages can give us some hints.

Tables 9 and 10 show the top 10 most frequent constructs per type in the last versions of Java and Kotlin apps, respectively. Comparing the two tables reveals distinct behavior patterns: for Kotlin, none of the top ten constructs relates to null-checking; however, for Java’s instances reported in Table 9, 84.48% of preconditions and 73.05% of postconditions are associated with null-checking. In this number, we are not considering potential IllegalArgumentException and IllegalStateException that could be associated with null-checking since this would require analyzing the condition in the if-statement. This suggests a lack of expressiveness in the contracts specified by Java practitioners, with most being associated with null-checking, consistent with prior studies [33, 15].

This contrast in null-checking contracts between Java and Kotlin is easily explained by the languages’ different takes on nullability. In Kotlin, regular types are non-nullable by default; therefore, in most cases, practitioners do not have the need for constructs like AndroidXNonNull or JSR305NonNull. On the other hand, it is interesting to observe that relaxing this constraint to allow nullable types is not a common practice since we found no meaningful use of constraints like AndroidXNullable and similar in Kotlin.

Table 11 presents the number of contracts in both versions by category. The Type column presents all types that are supported. In general, for most cases, the number of contracts in each category increased from the first to the last version. The only category where the number decreased was the Apache’s Commons Validate for Java.

We computed some metrics to understand how the increase in the program’s size relates to the number of contracts (see Table 12). These include the average and median values for the number of methods, the number of contracts, and the ratio between both (for both versions). The table shows that there is an average increase of about 114.185 methods per program. This is expected since the program’s size tends to increase from the first to the second version. However, a more interesting insight comes from the contracts count. Although the average number of contracts per program increased, its median value decreased. This means that the dataset includes outliers with a significant rise in contract usage that considerably affected the average value. To confirm this data, we computed the ratio between the number of contracts and the number of methods for each version of a program. Then, we computed the difference between the second and the first version’s ratio for each program. The average of these differences is -0.0077, and the median is -0.0012. Although the values are very small, we conclude that the number of methods increases significantly more than the number of contracts.

Similarly to our study, Dietrich et al. [13] also found that the median value of the ratio does not change much. Still, while we observed a decline between the two versions (from 0.038 to 0.030), they reported an increase (from 0.021 to 0.023). This means that although both studies show general stability related to contracts usage, contrary to their study, we were not able to find a positive correlation between the increase in the number of methods and in the number of contracts.

To address whether practitioners tend to misuse contracts in either program evolution or inheritance contexts, we build diff records to be classified according to evolution patterns. Some of these evolution patterns are associated with a potential risk that may lead to client breaks, namely when preconditions are strengthened or postconditions are weakened. This process was described in more detail in Sections 4.3.3 and 4.3.4. It is important to note that the analysis tool cannot precisely capture all contract changes due to the variety of constructs we are analyzing and the complexity of their semantics. This can potentially lead to under-reporting. Another factor that may contribute to under-reporting is file path changes between versions, which may lead to no evolution patterns being detected. Even so, Table 13 still provides valuable insights into the safety of contract usage and evolution. The table shows the frequency of each evolution pattern in the context of program evolution (third column). We see that many contracts remain unchanged and that most changes are not critical. However, most of the changes that occur can lead to potential breaks, with precondition strengthening being over three and a half times more prevalent than postcondition weakening. An example of a precondition strengthening using an annotation and taken from our dataset was already shown in  Subsubsection 4.3.3. The code is from the class ToolbarContentTintHelper in project Retro Music Player,¹²¹²12https://github.com/RetroMusicPlayer/RetroMusicPlayer (last accessed on 01 April 2025) a music player for Android. Adding @NonNull to the toolbar parameter strengthens the precondition by explicitly requiring callers to pass a non-null Toolbar instance, potentially breaking clients that previously relied on more permissive behavior. footnote 13 shows an example of a postcondition weakening. The code is taken from class SyncProcessor in project mGerrit,¹³¹³13https://github.com/JBirdVegas/external_jbirdvegas_mGerrit (last accessed on 01 April 2025) a Gerrit client for Android. The postcondition is weakened because the @NotNull annotation promises a non-null Intent, but if intent is ever null, this contract is violated – potentially leading to runtime errors like NullPointerException in callers that rely on the non-null guarantee.

Finally, Table 13 also presents the results found for evolution patterns in the context of inheritance (fourth column). We observe that the precondition strengthening pattern makes up almost 50% of classified instances. We also note that from the classified instances, most parts are related to contract changes which means a lack of stability in specifications. Both in the evolution and the inheritance study, we found lower occurrences of postcondition weakening when compared to the other classifications. Also, compared to the reports from Dietrich et al.’s study [13], our results indicate a greater ratio of precondition strengthening per preconditions found.

Based on our findings, we answer the research questions posed in Section 4.1 as follows:

Our findings lead to the following practical implications and recommendations.

To evaluate the recommendations we derived from our findings, and to gather challenges faced by practitioners when using contracts, we conducted a qualitative survey study with 16 practitioners. In particular, we are interested in answering the following research questions (SRQs):

• $\mathrm{■}$

  SRQ1. [Challenges] What are the main challenges that users face when using contracts?

• $\mathrm{■}$

  SRQ2. [Recommendations] What do users recommend to increase contracts’ adoption?