bisq-network / bisq-network/style

Organize imports with common layout

Open
#2 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
2
Forks
2
PR merge metrics
No merged PRs in 30d

Description

We keep a master `.idea/codeStyles/` directory in the root of the https://github.com/bisq-network/dao repository. This directory contains a `Project.xml` with an `IMPORT_LAYOUT_TABLE` to be used across all `bisq-*` Java projects. We keep this file up to date and copy it to all `bisq-*` repositories whenever changes to the import layout are necessary.

There is nothing you need to do to set this up. If you're using IDEA to work on `bisq-*` projects, everything should "just work", because the project you're working on already has a copy of these settings in its own `.idea/codeStyles` directory.

If you introduce a new import to a `bisq-*` repository that is not yet listed in the common import layout table, it will get sorted at the bottom of the import list, preceded by several blank lines. This is your clue that you need to add an entry to the import table. You can do this locally in your project, i.e. directly in its `.codeStyles/Project.xml`, or you can do it at the root `bisq-network/dao` repository level and copy it everywhere. All that matters is that the change gets committed and that imports get laid out correctly.

The order of imports in the layout table is not alphanumeric. It is based on how high or low level the package is in the overall layering of all packages.

- `bisq.*` packages are always sorted at top
- then packages that are close to Bisq's domain, e.g. `org.bitcoinj`
- and from there, infrastructure packages are ordered according to their dependencies on one another or a rough estimation of how high or low level they are relative to one another

This approach to ordering imports is all about providing maximum at-a-glance information to the reader of the source. By simply looking at the name of a class and its imports, a reader should be able to get a good sense of what that class does, what it "touches", what it is responsible for, etc. Indeed, taking an intentional approach to import organization and using this metadata as a code comprehension tool can help provide early warnings about when a class is starting to do too much, get tangled up with other packages and layers, etc.

Recommendation: disable the default "import folding" setting in IDEA. Keep imports "in your face" and use them to your advantage to keep types, packages and layers clean.

![Editor > General > Code Folding > Imports](https://imgur.com/KXAB6yM.png)

See:
- https://confluence.jetbrains.com/display/IDEADEV/New+project+code+style+settings+format+in+2017.3
- https://www.jetbrains.com/help/idea/2017.3/copying-code-style-settings.html

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with .idea/codeStyles/Project.xml in the repository root and inspect its IMPORT_LAYOUT_TABLE and the corresponding files in bisq-* repositories. Identify the import entry or layout change that is actually needed, then verify that the committed settings produce the intended ordering across the affected projects.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.