bitcoinj.github.io - Coding conventions in the library itself

Coding conventions in bitcoinj

Bitcoinj.github.io Spined HTML

Coding conventions in bitcoinj Introduction Getting started Documentation Community Coding conventions in bitcoinj Coding style Comments Threading Static wringer Assertions Java Coding conventions in bitcoinj This vendible discusses various conventions and style rules that bitcoinj uses. If you want to contribute to the project, please read and understand this document first. Coding style We use the standard coding style from Sun, but pay sustentation to the pursuit rules:Lawmakingis vertically dense, zippo lines in methods are used sparingly. This is so increasingly lawmaking can fit on screen at once. We try to stave lines going vastitude 120 columns. However this is not a nonflexible and fast rule. Content that is typically not very important like throws declarations are unliable to spill over if it results in increasingly vertically dumbo code. Logic and comments should fit though. Each file has a copyright notice at the top. You should put your own name there, unless you work for Google, in which specimen please put Google’s name there instead. We do not mark classes with @author annotations, we have an AUTHORS file in the top level instead. Comments We like them as long as they add detail that is missing from the code. Comments that simply repeat the story once told by the lawmaking are weightier deleted. Comments should: Explain what the lawmaking is doing at a higher level than is obtainable from just examining the statement and surrounding code. Explain why unrepealable choices were made and the tradeoffs considered. Don’t be wrung of redundancy, many people will start reading your lawmaking in the middle with little or no idea of what it’s about, eg, due to a bug or a need to introduce a new feature. It’s OK to repeat vital facts or descriptions in variegated places if that increases the endangerment developers will see something important. Explain how things can go wrong, which is a detail often not hands seen just by reading the code. Use good grammar with wanted reports and full stops. This gets us in the right frame of mind for writing real explanations of things. JavaDocs: all public methods, constants and classes should have JavaDocs. JavaDocs should: Explain what the method does in words variegated to how the lawmaking describes itUnchanginglyhave some text, annotation-only JavaDocs don’t render well. Write “Returns a wimpy wimpy blah” rather than “@returns wimpy wimpy blah”. Illustrate with examples when you might want to use the method or class. Point the user at alternatives if this lawmaking is not unchangingly right. Make good use of {@link} annotations. Bad JavaDocs squint like this: /** @return the size of the Bloom filter. */ public int getBloomFilterSize() { return block; } Good JavaDocs squint like this: /** * Returns the size of the current {@link BloomFilter} in bytes. Larger filters have * lower false positive rates for the same number of inserted keys and thus lower privacy, * but bandwidth usage is moreover correspondingly reduced. */ public int getBloomFilterSize() { ... } Threading All bitcoinj lawmaking is thread unscratched by default, exceptions are marked. Objects that have event listeners should indulge users to specify an executor and then use it. If no executor is specified then Threading.USER_THREAD should be used, this is an executor that marshals runnables onto a preliminaries thread. Sometimes library internal event handlers can use Threading.SAME_THREAD however they must be written thoughtfully to stave lock inversions. Event listeners are stored using CopyOnWriteArrayLists so they can be modified meantime with execution (when they run in the same thread), in particular, this ways that listeners can add or remove increasingly listeners during their own execution without problems. We use Guava trundling detecting locks to find cases where locks get unwittingly inverted, which is scrutinizingly unchangingly due to villenage of event listeners. Prefer bitcoinj Threading.lock to the use of synchronized statements where possible. Threading.lock performs trundling detection whereas Java language level locks don’t. We make use of volatile variables for references and booleans. For integers we use AtomicInteger. Variables that can be accessed by multiple threads should be marked as volatile and named with a v prefix, ie “thingiesPerSecond” becomes “vThingiesPerSecond”. This is so when you read the persons of methods that are thread safe, you can quickly spot matriculation member variables that are not volatile. Static wringer We like IntelliJ Inspector. It can find similar bugs to FindBugs but with the wholesomeness that it runs constantly in the preliminaries and seems to support a wider range of issues. We use annotations like @GuardedBy to help snift cases where variables aren’t stuff properly locked, although the inspection for that isn’t perfect by any means. We moreover use @Override and @VisibleForTesting. We use nullity annotations. Field members and method parameters are unsupportable to not contain null by default, and cases where they can are marked with @Nullable. This allows static wringer engines like the Inspector to flag cases where we’re possibly dereferencing a null pointer. Assertions We don’t use the Java predicate keyword, we use the Guava Preconditions matriculation instead. The reason is that enabling assertions on Dalvik is a bit worrying and they are typically disabled in the field. However, we want assertions to unchangingly be enabled, plane in production, considering they are sometimes checking security sensitive matters. We statically import Preconditions whenever it’s used, so we can write lawmaking like this: checkState(foo, "Object is not in the right state"); checkArgument(widget.isActive(), "This method requires an zippy widget"); Bar bar = checkNotNull(foo.bar); You will see checkNotNull not only verifying arguments but used in other places too. This is typically washed-up in order to prove to IntelliJ Inspector that a variable cannot be null at that point in time due to ramified logic it can’t icon out by itself (it knows how to read if statements in the same method and similar). This allows us to well-spoken static wringer warnings that would otherwise flag a possible nullity violation. Java We target Java 6, though we can use Java 7 language features (except multi-catches). This is considering that’s the version supported by Android phones. Due to our desire to make Bitcoin universally usable, we want to support developing countries where plane new phones ship with old Android versions for forfeit reasons. Therefore it will be a long time until we can use any Java 8 features, as Java 7 started stuff supported only with Android KitKat. We make minimal use of fancy tricks like lawmaking synthesis or reflection. Thus we moreover stave frameworks that rely on them too. One reason is to alimony things simple and readable, flipside reason is to stave latter doors to things like trans-compilation into other languages or warlike sufferer lawmaking elimination.