thoth-tech / programming-arcana

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Programming Arcana

The Programming Arcana is an open source programming text book that focuses on teaching introductory programming concepts.

The guiding principles are:

  • Transferable concepts are more important than language specifics
  • Build concepts on top of known concepts as much as possible
  • Focus on procedural programming initially, with a view to transitioning to objects
  • Build programs that make it easy to see what is happening in the code

Code formatter

We use clang-format as our code format for this project.

Installation

Linux

clang-format can be installed by:

sudo apt install clang-format

macOS

clang-format can be installed by:

brew install clang-format

Windows

The executable file can be downloaded from llvm org.

Other

The clang-format can also be installed with python and nodejs:

# python
python3 -m pip install clang-format

# nodejs
npm install -g clang-format

The VS code extension. (optional, clang-format required)

The format style

The base format style used is google.

Usage

Validate code

A python script from Sarcasm is used to validate the code.

For example, you can use check if the file ./code/c/array/array-copy.c needs to be formatted.

# use python instead of python3 if python version is 2
./script/run-clang-format.py  ./code/c/array/array-copy.c

The output would be

--- ./code/c/array/array-copy.c (original)
+++ ./code/c/array/array-copy.c (reformatted)
@@ -2,14 +2,13 @@

 #include <string.h>

-int main()
-{
-    int data[3] = {1, 2, 3};
-    int other_data[3];
-    int more_data[3];
-
-    memcpy(other_data, data, 3 * sizeof(int));
-    memcpy(more_data, data, sizeof(data));
-
-    return 0;
+int main() {
+  int data[3] = {1, 2, 3};
+  int other_data[3];
+  int more_data[3];
+
+  memcpy(other_data, data, 3 * sizeof(int));
+  memcpy(more_data, data, sizeof(data));
+
+  return 0;
 }%

*Python3 is normally installed as a default package in most operating systems. However, if you are using Windows and do not want to install Python, you can use clang-format .\code\c\array\array-copy.c . However, it would not have the feature in the wrapper script, for example, coloured output.

Format code

For a single file you can use command:

clang-format -i <file name>

Or if you have VS code extension installed you can use right click -> Format Document With ... option.

In order to recursively format all files, you can use:

# windows user
# using powershell
Get-ChildItem -recurse -path .\* -include *.c, *.cpp| ForEach-Object{clang-format -style=file -i $_}
# need python3 installed
# using wrapped script
./script/run-clang-format.py -ri .

Branch prefixes

When branching, try to prefix your branch with one of the following:

Prefix Description Example
feature/ New feature was added feature/add-learning-outcome-alignment
fix/ A bug was fixed fix/crash-when-code-submission-finished
enhance/ Improvement to existing feature, but not visual enhancement (See LOOKS) enhance/allow-code-files-to-be-submitted
looks/ UI Refinement, but not functional change (See ENHANCE) looks/rebrand-ui-for-version-2-marketing
quality/ Refactoring of existing code quality/make-code-convention-consistent
doc/ Documentation-related changes doc/add-new-api-documentation
config/ Project configuration changes config/add-framework-x-to-project
speed/ Performance-related improvements speed/new-algorithm-to-process-foo
test/ Test addition or enhancement test/unit-tests-for-new-feature-x

Commit message format

We have precise rules over how our Git commit messages must be formatted. This format makes it easier to read the commit history.

Each commit message consists of a header, a body, and a footer.

<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The header is mandatory and must conform to the Commit Message Header format.

The body is recommended for all commits. When the body is present, it must be at least 20 characters long and conform to the Commit Message Body format.

The footer is optional. The Commit Message Footer format describes the purpose and structure of the footer.

Any line of the commit message should be 100 characters or fewer.

Commit Message Header
<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │       │
  │       └─⫸ Commit Scope (optional): animations|common|style|forms|http|router|service-worker|
  │                                     upgrade|changelog|dev-infra|docs-infra|migrations|
  │
  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test

The <type> and <summary> fields are mandatory, the (<scope>) field is optional.

The <type> must be one of the following:

  • 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: 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
  • test: Adding missing tests or correcting existing tests

We recommend reading Chris Beam's post on How to Write Good Commit Messages.

About

License:Creative Commons Attribution 4.0 International


Languages

Language:TeX 73.2%Language:C 10.8%Language:Pascal 9.6%Language:Python 4.1%Language:C++ 2.4%Language:Shell 0.0%