244 lines
6.7 KiB
Markdown
244 lines
6.7 KiB
Markdown
# Baja Software Comment and Function Template
|
||
|
||
## Why and How To Comment
|
||
|
||
How long do you think this code will be used? 1 year? 1 decade? 4 weeks?
|
||
|
||
In Baja Software it should be belived that at some point you will be gone before the end of the lifetime of the software application.
|
||
|
||
Since you dont know when the end of the software's lifetime is; make life easier on both your future self and new juniors by comments the code, you dont have to comment line by line, but anything that isnt overtly clear should be commented.
|
||
|
||
A general guidline to comments:
|
||
1. Comment Functions/Methods using the [Standard Function Template](#templates)
|
||
1. Anything unclear to your past self (before creating it) should be commented
|
||
1. At minimum comment explain what a "block" or scope does
|
||
1. The rule in highest order can "overshadow" lower rules making them not required, for example a function that adds two integers does not need anything more than a well written [standard function template](#templates)
|
||
|
||
|
||
You don't know so make life easier on yourself and new juniors comment on what your code does, it doesn't have to be line by line but at least explain a "block" or a related section of code to the purpose/what it does.
|
||
|
||
## Templates
|
||
|
||
All templates based off JSDoc standard can be found [here](https://jsdoc.app) and markdown
|
||
|
||
### Quick Links
|
||
1. [JavaScipt](#javascript)
|
||
1. [Python](#python)
|
||
1. [Rust](#rust)
|
||
1. [C++](#c)
|
||
1. [C](#c-1)
|
||
1. [Java/C#](#javac)
|
||
1. [Go/Golang](#golang)
|
||
1. [Lua](#lua)
|
||
1. [Terraform](#terraform)
|
||
1. [HTML](#html)
|
||
1. [JSON, YAML, XML, CSS](#json-yaml-xml-css)
|
||
1. [Bash](#bash)
|
||
1. [Github Actions](#github-actions)
|
||
|
||
### JavaScript
|
||
|
||
Uses [JSDoc](https://jsdoc.app) standard
|
||
|
||
```js
|
||
//More preferred arrow function just needs to call function and does function immediately
|
||
/**
|
||
* @param {Object} inputVar - one argument into the function should be its name
|
||
* @param {number} b - one argument into the function should be its name
|
||
* @returns {Promise<number>} c - what the program returns with type
|
||
* @description A brief description of what the function does
|
||
* @author Name <semiperminant@exmaplemail.com>
|
||
// semi-permanent email, do not need to respond but try to be a good alumni
|
||
*/
|
||
const exampleFunct = (inputVar) => {
|
||
// comments annotate the line below them
|
||
// constant variable cannot change, not strongly typed
|
||
const varExample0 = 0;
|
||
// local variable, not strongly typed can be any data type
|
||
let varExample1 = 0;
|
||
// global variable, not strongly typed can be any data type
|
||
var varExample2 = 0;
|
||
// example function does nothing significant
|
||
return 0;
|
||
};
|
||
|
||
/**
|
||
* @param {Object} inputVar - one argument into the function should be its name
|
||
* @param {number} b - one argument into the function should be its name
|
||
* @returns {Promise<number>} c - what the program returns with type
|
||
* @description A brief description of what the function does
|
||
* @author Name <semiperminant@exmaplemail.com>
|
||
// semi-permanent email, do not need to respond but try to be a good alumni
|
||
*/
|
||
function exampleFunct2(inputVar) {
|
||
// comments annotate the line below them
|
||
// constant variable cannot change, not strongly typed
|
||
const varExample0 = 0;
|
||
// local variable, not strongly typed can be any data type
|
||
let varExample1 = 0;
|
||
// global variable, not strongly typed can be any data type
|
||
var varExample2 = 0;
|
||
// example function does nothing significant
|
||
return 0;
|
||
|
||
};
|
||
```
|
||
|
||
### Python
|
||
|
||
```python
|
||
# comments normally annotate the line below, python functions/classes/methods are the only expection
|
||
def example_funct(input_var:type):
|
||
"""
|
||
What function does
|
||
|
||
`PARAMS`:
|
||
- Name_of_var `type` - Addtional details of what is required
|
||
|
||
`RETURNS`:
|
||
- Name_of_var `type` - Additional details of what is required
|
||
|
||
`AUTHOR(S)`:
|
||
- Your Name
|
||
|
||
`Contact`:
|
||
- semi-permanent email, do not need to respond but try to be a good alumni
|
||
- Example of two items
|
||
"""
|
||
|
||
# example variable can be anything not just an int
|
||
var_example = 0
|
||
# example function does nothing significant
|
||
return 0
|
||
```
|
||
|
||
### Rust
|
||
|
||
```rust
|
||
fn exampleFunc () {
|
||
// I have not decided yet
|
||
}
|
||
```
|
||
|
||
### C++
|
||
|
||
```cpp
|
||
/*
|
||
What function does
|
||
|
||
PARAMS:
|
||
- nameOfVar `type` - Addtional Detals (if applicable)
|
||
|
||
PROMISES:
|
||
- nameOfVar `type` - Additional Details (if applicable)
|
||
|
||
AUTHOR(S):
|
||
- Your Name
|
||
|
||
CONTACT:
|
||
- semi-permanent email, do not need to respond but try to be a good alumni
|
||
- Example of two items
|
||
*/
|
||
int exampleFunct (int inputVar) {
|
||
// comments annotate the line below them
|
||
int varExamlpe;
|
||
// example variable, is strongly typed. Can only be an integer
|
||
int varExample1 = 0;
|
||
// example function does nothing significant.
|
||
return 0;
|
||
};
|
||
```
|
||
|
||
### C
|
||
|
||
```c
|
||
/*
|
||
What function does
|
||
|
||
PARAMS:
|
||
- nameOfVar `type` - Addtional Detals (if applicable)
|
||
|
||
PROMISES:
|
||
- nameOfVar `type` - Additional Details (if applicable)
|
||
|
||
AUTHOR(S):
|
||
- Your Name
|
||
|
||
CONTACT:
|
||
- semi-permanent email, do not need to respond but try to be a good alumni
|
||
- Example of two items
|
||
*/
|
||
int exampleFunct (int inputVar) {
|
||
// comments annotate the line below them
|
||
int varExample0;
|
||
// exampe variable is strongly typed. In this case can only be an integer
|
||
int varExample1 = 0;
|
||
// example function does nothing significant
|
||
return 0;
|
||
};
|
||
```
|
||
|
||
### Java/C#
|
||
```java
|
||
// these languages is cursed and full of boilerplate
|
||
// use anything else if you can
|
||
// high memory overhead, use C++ instead
|
||
// you can add standard here just make it similar to the rest
|
||
```
|
||
|
||
### Golang
|
||
```golang
|
||
// I dont know
|
||
// you can add standard here just make it similar to the rest
|
||
```
|
||
|
||
### Lua
|
||
```lua
|
||
-- I dont know
|
||
-- you can add standard here just make it similar to the rest
|
||
```
|
||
|
||
### Terraform
|
||
This will probably only used for cloud applications
|
||
```terraform
|
||
<!--
|
||
I dont know
|
||
you can add standard here just make it similar to the rest
|
||
-->
|
||
```
|
||
|
||
### HTML
|
||
This is the same as any other page, not unique, should still vet in a html validator/best practices
|
||
author goes in human.txt, for more info please see [here](https://humanstxt.org)
|
||
|
||
```html
|
||
<!doctype html>
|
||
<html>
|
||
<head>
|
||
<title>Our Funky HTML Page</title>
|
||
<meta name="description" content="Our first page">
|
||
<meta name="keywords" content="html tutorial template">
|
||
</head>
|
||
<body>
|
||
Content goes here.
|
||
</body>
|
||
</html>
|
||
```
|
||
|
||
### JSON, YAML, XML, CSS
|
||
These are more like data types/file format, follow rules of the language
|
||
|
||
### Bash
|
||
Always starts with a shebang
|
||
```bash
|
||
#!
|
||
echo "Hello World!"
|
||
# I dont know
|
||
# you can add standard here just make it similar to the rest
|
||
```
|
||
|
||
### Github Actions
|
||
|
||
Please find example in any baja repo under .github/workflows/*.yaml
|
||
|
||
star is a wildcard and in this case represents any name of the file |