From 106efe5470ca48d99ac1fd466be530f1e303f5cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20K=C3=BCrten?= Date: Wed, 2 Dec 2020 14:38:24 +0100 Subject: [PATCH] Add section about patterns for visibility and interfaces --- development-101.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/development-101.md b/development-101.md index 41301ac..e1ae0b8 100644 --- a/development-101.md +++ b/development-101.md @@ -13,4 +13,31 @@ During development you may find yourself having to enter your briar password ver The project uses the Gradle Witness to make sure third party dependencies have not been tampered with. If you encounter problems with this feature, for example after upgrading dependencies, it may be required to recalculate the checksums: - ./update-dependency-pinning.sh \ No newline at end of file + ./update-dependency-pinning.sh + +## Patterns for visibility and interfaces + +As an addition to the points noted in the +[pre review checklist](https://code.briarproject.org/briar/briar/-/wikis/pre-review-checklist): + +the convention we usually follow is that classes should be package-private. If +they're used outside their package, it should be via a public interface, with +the impl bound to the interface via Dagger. + +There are a few exceptions to this convention: + +* Activities, fragments, etc generally need to be public so the framework can + instantiate them +* Dagger modules need to be public +* JUnit tests need to be public +* bramble-api and briar-api contain some public "data classes" (eg Contact) - + these are immutable and shouldn't contain any significant logic +* There are a handful of public classes in bramble-api and briar-api that do + contain significant logic (eg BdfDictionary) - these are so widely used that + injecting them would add a lot of boilerplate +* We have a few public utility classes (eg StringUtils) with static utility + methods to reduce code duplication + +Additionally we sometimes also use interfaces within packages. +It can help establishing a clearer separation of concerns and easier testing +when there's complex interaction between classes.