Documentation Guidelines

THIS REALLY NEEDS A REWORK

Common Code

All code should always be written in a way, that the purpose of the code is revealed on first sight. This means that for example that the purpose of a defined function should be entirely clear after just reading its name, its parameters and its return type. The same is true for variables. (Even if this means longer names)

If, in some cases, it is not possible to name your function concisely, the function should be commented with a block comment like this:

/// Adds two integers [a] and [b] and returns their sum
int add(int a, int b) {
 return a + b;
}

For best practices, visit here Documentation of Dart Code.

If the above is the case, you should perhaps also consider refactoring your function.

Sometimes it is not intuitively clear why you are doing something the way you have done it. In such cases, please add a short comment to explain your solution.

Tools

Sometimes you will have to write additional libraries and tools, which just provide a few public functions to use and configure the tool. In such cases, please document your tool on a new page in this wiki, to explain how your tool should be used and configured. Otherwise, developers that are new to the project might not even know that your tool exist and could end up writing their own.

Unfinished Business

If you leave something off for another day, found a bug, that you will not fix immediately or need someone else to look over a specific part of your code, please use the TODO Tag:

// TODO: @Otis Did I miss something?