Baja-Charter/Software Standardizations and Common Git Commands.MD

This section outlines how programming and coding in all languages should generally be followed.

1. Readable code is valued above all else ie. Variable names that make sense, clear function names
2. Comment code even if it is obnoxious make it so that you or anyone besides yourself in 10 years can read what is going on.   Programs like ChatGPT are allowed to comment code automatically just as long as they make sense to you six months down the road
3. Use the Prettier extension as the default code formatter so that the code is consistent
4. Use git and use a new branch to create a new feature (be careful of the base of the branch)
5. Use pull requests to the dev branch to merge code        

DO NOT MERGE TO THE PRODUCTION BRANCH (main or master normally)

1. Examples of base templates in most common languages are available below
2. Try to make code as modular and reusable as possible
3. Use ChatGPT but be warned you will spend more time on debugging than coding and most importantly YOU WONT LEARN, USE IT FOR REGEX
4. Please include a permanent email and name if you write any code, this is just for questions on what x does (not mandatory)     - If you write unreadable code you get emails in the future about it     - Remove emails if completely refactored (75% of the code has been changed in some way)

DO NOT USE THIS TO GET ALUMNI TO DO YOUR WORK

Git

The stupid content tracker. No more need for V1, V2, V2 Final or V2 Final Final edit by Malik Final

This terminal-based program is a lightweight version control, that is highly useful for dealing with code/text activities. This does not require a remote origin, a local repo will be fine with the use of the Baja Cloud, just upload any .git files with it. This will track everything in the specified git directory (files, child directories, etc.)

Common Commands

Note

Need to be in a git repo directory to use git commands.

# change directory
cd <name/path>

# Go to the parent directory
cd.

# initialize a git repository (local only)
git init

# add (stage) all changes (in files)
git add -A

# Commit staged changes with a message
git commit -m "commit message"

# create a new branch and check into it
git checkout -b <branch-name>

# change the current branch to an existing branch
git checkout <branch-name>

# delete a branch
git branch -D <branch-name>

# set upstream (default remote branch) for a local branch
# (upload)
git push -u origin <branch-name>

# pull the latest changes from the remote repository
# (download)
git pull origin <branch-name>

# revert a commit
git revert <commit-hash>

# see commit logs (multi-line includes the date, who and other useless info)
# Is much longer
git log

# see logs in one line (with commit hash)
# shorter
git log --oneline

# see the list of both local and remote branches
git branch -a

# see the list of local branches
git branch

# see the status of the current local repository
# see what files/changes are uncommitted
git status

# rebase a branch with another one
git rebase <branch-name>

# see remote repositories linked to the current local repository
git remote -v

# add a new origin (remote repository)
git remote add origin <origin-url>

# cache GitHub credentials
git config --global credential.helper 'cache --timeout=36000'

# remove git cache
git rm -r --cached.

# config username and email for a git project
git config user.name "username"
git config user.email "email"

Git cheat sheet

The commands discussed above–and more–are summarized in this cheat sheet available to download.

Type

Must be one of the following:

• init: A special case only for the very first commit (example: init(location))
• build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
• ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
• docs: Documentation only changes
• feat: A new feature
• fix: A bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• style: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc)
• test: Adding missing tests or correcting existing tests
• chore:
• added: Added content but not a complete feature
• removed: Removed files or content only
• merged: Used when a branch's content is merged into another branch

Message

The subject contains a succinct description of the change (this will show up in the logs):

• use the imperative, present tense: "change" not "changed" nor "changes"
• don't capitalize the first letter
• no dot (.) at the end

How to Commit

"<type>(scope or file that has been changed): short description"

Replace with just the type ^ for any breaking commits

Example

git add -A # adds all of the files/changed files to the commit stage (pre-commit)

git commit -m"feat(DAQ)^: optimized algorithm" # the message that will show up in the logs

Another Example

git commit -m"Feat (API)^: send an email to the customer when a product is shipped"

Why?

How long do you think this code will be used? 1 year? 1 decade? 4 weeks? 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.

Example Comments and Function Starters

Based off JSDoc standard

JavaScript

Uses JSDoc standard

//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

# 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

fn exampleFunc () {
 //I have not decided yet
}

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 varExamlpe;
    // example variable, is strongly typed. Can only be an integer
    int varExample1 = 0; 
    // example function does nothing significant.
    return 0; 
};

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#

// 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

// I dont know
// you can add standard here just make it similar to the rest

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

<!-- 
    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

<!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

#!
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