diff --git a/Style-Guide.md b/Style-Guide.md new file mode 100644 index 0000000..f6fa4e1 --- /dev/null +++ b/Style-Guide.md @@ -0,0 +1,55 @@ +# Comments +## Documentation Comments + +Before each thing that has package-level scope, whether it is public or private, there must be a descriptive documentation before it. These serve as documentation. In accordance with how Go documentation comments are conventionally written, they must: + +- Start with the thing's name +- If it's a function, focus on explaining *what* the functions does, not how it does it +- Be a proper readable sentence; a paragraph if a more lengthy description is required +- Not be block comments—each line should start with `//` + +For example: + +``` +// Parse reads the files located in the module specified by modulePath, and +// converts them into an abstract syntax tree. +func Parse (modulePath string) (tree *SyntaxTree, err error) { +``` + +## Inline Comments + +Comments within the actual code are generally all lowercase, and do not end with a period. They should provide a high level description of what code is doing. This goes without saying, but be sure to include a good amount of these, as other people *will* read your code. + +An extremely useful way to use comments is as headers to separated blocks of code, like in the example shown below: + +``` +// get permission +err = parser.nextToken(lexer.TokenKindPermission) +if err != nil { return } +section.permission = parser.token.Value().(types.Permission) + +// get name +err = parser.nextToken(lexer.TokenKindName) +if err != nil { return } +section.name = parser.token.Value().(string) + +// parse inherited type +err = parser.nextToken(lexer.TokenKindColon) +if err != nil { return } +err = parser.nextToken() +if err != nil { return } +section.what, err = parser.parseType() +if err != nil { return } +err = parser.expect(lexer.TokenKindNewline) +if err != nil { return } +err = parser.nextToken() +if err != nil { return } +``` + +# Returning Values + +Golang lets you return multiple values from functions, and it also allows you to give them names. When writing code for the compiler, all function + +# Nesting + +If you're indenting more than 4 times you should look into breaking up your code into more functions/methods. The control flow of functions with that much nesting can be very difficult to analyze. \ No newline at end of file