From cb72233f23b22b50a085381d11840838528eb5ef Mon Sep 17 00:00:00 2001 From: Daniel Micay Date: Wed, 10 Jul 2019 20:01:56 -0400 Subject: [PATCH] initial development guidelines section --- static/build.html | 123 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) diff --git a/static/build.html b/static/build.html index 4127b6b6..1af8964c 100644 --- a/static/build.html +++ b/static/build.html @@ -86,6 +86,14 @@ +
  • + Development guidelines + +

    • @@ -554,6 +562,121 @@ export PATH="$PATH:$HOME/sdk/tools:$HOME/sdk/tools/bin:$HOME/sdk/platform-tools:

    It's possible to run the whole standard CTS plan with a single command, but running specific modules is recommended, especially if you don't have everything set up for the entire test suite.

    + +

    + Development guidelines +

    + +

    + Programming languages +

    + +

    The following programming languages are acceptable for completely + new GrapheneOS projects:

    + + +

    Much of the work is done on existing projects, and the existing languages should be + used unless there are already clear stable API boundaries where a different language + could be used without causing a substantial maintenance burden. The following + languages are typical from most to least common: Java, C++, C, JavaScript, arm64 + assembly, POSIX shell, Bash.

    + +

    + Code style +

    + +

    For existing projects, use the official upstream code style. Avoid using legacy + conventions that they're moving away from themselves. Follow the code style they use + for new additions. Some projects have different code styles for different directories + or files depending on their sources, in which case respect the per-file style.

    + +

    For new projects, follow the official code style for the language. Treat the + standard library APIs as defining the naming style for usage of the language, i.e. C + uses variable_or_function_name, type_name, + MACRO_NAME while JavaScript uses variable_or_function_name, + ClassName and CONSTANT_NAME. For Python, follow PEP8 and the + same goes for other languages with official styles whether defined in a document or by + the default mode for the official formatting tool like rustfmt.

    + +

    For cases where there isn't an official or prevailing code style for other things, + avoid tabs, use 4-space indents, function_name, + variable_name, TypeName and CONSTANT_NAME. + Prefer single-line comment syntax other than rare cases where it makes sense to add a + tiny comment within a line of code. In languages with the optional braces misfeature + (C, C++, Java), always use them. Open braces on the same line as function definitions + / statements. Wrap lines at 100 columns except in rare cases where it would be far + uglier to wrap the line.

    + +

    For JavaScript, put "use strict"; at the top of every file, end lines + with semicolons (since automatic insertion is poorly designed) and always use + const to declare variables, unless they are mutated in which case they + should be declared with let but never use var as it is + effectively broken. Try to prefer loops with for..of.

    + +

    Avoid designing around class inheritance unless it's a rare case where it's an + extremely good fit or the language sucks (Java) and it's the least bad approach, but + still try to avoid it.

    + +

    Use concise but self-explanatory variable names. Prefer communicating information + via naming rather than using comments whenever possible. Don't name variables + i, j, k, etc. like C programmers. It's okay to + use things like x and y for parameters if the function is + genuinely that generic and operates on arbitrary values. In general, try to scope + variables into the most limited scope (in C or C++, be careful about this when + references are taken).

    + +

    Write code that's clean and self-explanatory. Use comments to explain or justify + non-obvious things, but try to avoid needing them in the first place. In most cases, + they should just be communicating non-local information such as explaining why an + invariant is true based on the code elsewhere (consider a runtime check to make sure + it's true, or an assertion if performance would be an issue). Docstrings at the top of + top-level functions, modules, etc. are a different story and shouldn't be avoided.

    + +

    + Library usage +

    + +

    Make extensive usage of well designed standard library modules. For apps, treat + Jetpack (androidx) as part of the standard library and make good use of it. For Java, + Guava can also be treated as part of the standard library.

    + +

    Libraries outside of the standard library should be used very cautiously. They + should be well maintained, stable, well tested and widely used. Libraries implemented + with memory unsafe languages should generally be avoided (one exception: SQLite).

    + +

    Generally, frameworks and libraries existing solely to provide different paradigms + and coding patterns are to be avoided. They increase barrier to entry for developers, + generally only increase complexity unless used at very large scales (and may not even + make things simpler in those cases) and come and go as fads. This is only okay when + it's part of the standard libraries or libraries that are considered standard + (androidx, Guava) by GrapheneOS and should still be approached cautiously. Only use it + if it truly makes the correct approach simpler. Ignore fads and figure out if it + actually makes sense to use, otherwise just stick to the old fashioned way if the + fancy alternatives aren't genuinely better.

    +