Skip to content

Commit f95f54d

Browse files
robvanderleekrobvanderleek
committed
docs: 📝 Update docs
1 parent 4ff08db commit f95f54d

File tree

6 files changed

+177
-123
lines changed

6 files changed

+177
-123
lines changed

‎docs/quickstart.md renamed to ‎docs/getting-started/development-workflow.md

+27-70
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,4 @@
1-
# Quickstart
2-
3-
Depending on your development workflow, Code Limit can run as:
4-
5-
- [Pre-commit hook](#pre-commit-hook)
6-
- [GitHub Action](#github-action)
7-
- Standalone
8-
- [Homebrew](#homebrew-install)
9-
- [Pipx](#pipx-install)
10-
- [Pypi](#pypi-install)
11-
- [Platform binary](#platform-binaries)
12-
13-
## Pre-commit hook
14-
15-
Code Limit can be installed as a [pre-commit](https://pre-commit.com/) hook so
16-
it alarms you during development when it's time to refactor:
17-
18-
```yaml
19-
- repo: https://github.com/getcodelimit/codelimit
20-
rev: 0.6.2
21-
hooks:
22-
- id: codelimit
23-
```
24-
25-
Code Limit is intended to be used alongside formatting, linters and other hooks
26-
that improve the consistency and quality of your code (such as
27-
[Black](https://github.com/psf/black),
28-
[Ruff](https://github.com/astral-sh/ruff) and
29-
[MyPy](https://github.com/python/mypy).) As an example pre-commit configuration
30-
see the
31-
[`pre-commit-config.yaml`](https://github.com/getcodelimit/codelimit/blob/main/.pre-commit-config.yaml)
32-
from Code Limit itself.
33-
34-
When running as a hook, Code Limit *warns* about functions that *should* be
35-
refactored and *fails* for functions that *need* to be refactord.
1+
# Development workflow
362

373
## GitHub Action
384

@@ -47,55 +13,46 @@ your GH Action workflow:
4713

4814
```yaml
4915
name: 'main'
16+
5017
on:
5118
push:
52-
branches: main
19+
branches:
20+
- main
5321
pull_request:
54-
branches: main
22+
branches:
23+
- main
24+
5525
jobs:
5626
ci:
5727
runs-on: ubuntu-latest
5828
steps:
5929
- name: 'Checkout'
6030
uses: actions/checkout@v2
61-
- name: 'Run Code Limit'
62-
uses: getcodelimit/codelimit-action@main
63-
```
6431

65-
## Standalone
66-
67-
Code Limit can also run as a standalone program.
68-
69-
### Homebrew install
70-
71-
Code Limit is available on
72-
[Homebrew](https://formulae.brew.sh/formula/codelimit):
73-
74-
```shell
75-
brew install codelimit
76-
```
77-
78-
### Pipx install
79-
80-
To install the standalone version of Code Limit in an isolated Python
81-
environment using [pipx](https://pypa.github.io/pipx) run:
82-
83-
```
84-
pipx install codelimit
32+
- name: 'Run Code Limit'
33+
uses: getcodelimit/codelimit-action@v1
8534
```
8635
87-
### PyPi install
36+
## Pre-commit hook
8837
89-
To install the standalone version of Code Limit for your default Python
90-
installation run:
38+
Code Limit can be installed as a [pre-commit](https://pre-commit.com/) hook so
39+
it alarms you during development when it's time to refactor:
9140
92-
```shell
93-
python -m pip install codelimit
41+
```yaml
42+
- repo: https://github.com/getcodelimit/codelimit
43+
rev: 0.6.2
44+
hooks:
45+
- id: codelimit
9446
```
9547
96-
### Platform binaries
97-
98-
Binaries for different platforms (macOS, Linux, Windows) are available on the
99-
[latest release
100-
page](https://github.com/getcodelimit/codelimit/releases/latest).
48+
Code Limit is intended to be used alongside formatting, linters and other hooks
49+
that improve the consistency and quality of your code (such as
50+
[Black](https://github.com/psf/black),
51+
[Ruff](https://github.com/astral-sh/ruff) and
52+
[MyPy](https://github.com/python/mypy).) As an example pre-commit configuration
53+
see the
54+
[`pre-commit-config.yaml`](https://github.com/getcodelimit/codelimit/blob/main/.pre-commit-config.yaml)
55+
from Code Limit itself.
10156

57+
When running as a hook, Code Limit *warns* about functions that *should* be
58+
refactored and *fails* for functions that *need* to be refactord.

‎docs/usage.md renamed to ‎docs/getting-started/standalone-usage.md

+40-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,42 @@
11
# Standalone Usage
22

3+
## Installation
4+
5+
### Homebrew
6+
7+
Code Limit is available on
8+
[Homebrew](https://formulae.brew.sh/formula/codelimit):
9+
10+
```shell
11+
brew install codelimit
12+
```
13+
14+
### Pipx
15+
16+
To install the standalone version of Code Limit in an isolated Python
17+
environment using [pipx](https://pypa.github.io/pipx) run:
18+
19+
```
20+
pipx install codelimit
21+
```
22+
23+
### PyPi
24+
25+
To install the standalone version of Code Limit for your default Python
26+
installation run:
27+
28+
```shell
29+
python -m pip install codelimit
30+
```
31+
32+
### Platform binaries
33+
34+
Binaries for different platforms (macOS, Linux, Windows) are available on the
35+
[latest release
36+
page](https://github.com/getcodelimit/codelimit/releases/latest).
37+
38+
## Usage
39+
340
Run Code Limit without arguments to see the usage page:
441

542
```shell
@@ -23,7 +60,7 @@ $ codelimit
2360
╰──────────────────────────────────────────────────────────────────────────────╯
2461
```
2562

26-
## Scanning a codebase
63+
### Scanning a codebase
2764

2865
To scan a complete codebase run:
2966

@@ -33,7 +70,7 @@ codelimit scan path/to/codebase
3370

3471
<div id="scan.cast" style="z-index: 1; position: relative;"></div>
3572

36-
## Viewing a report
73+
### Viewing a report
3774

3875
To view the report with hard-to-maintain and unmaintainable functions of a
3976
codebase that was scanned before run:
@@ -47,7 +84,7 @@ codebase that was scanned before run:
4784
}
4885
</script>
4986

50-
## Checking files
87+
### Checking files
5188

5289
To check a single file or list of files for functions that need refactoring,
5390
run:

‎docs/index.md

+51-43
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,55 @@
1-
# Introduction
1+
<div align="center">
2+
<img src="assets/logo.png"/>
3+
</div>
4+
5+
<p align="center">
6+
<em>Your Refactoring Alarm</em>
7+
</p>
8+
9+
<div align="center">
10+
<a href="https://github.com/getcodelimit/codelimit/blob/_codelimit_reports/main/codelimit.md" target="_blank">
11+
<img src="https://github.com/getcodelimit/codelimit/blob/_codelimit_reports/main/badge.svg?raw=true" alt="Badge" class="off-glb">
12+
</a>
13+
</div>
14+
15+
No developer writes unmaintainable code on purpose, yet a lot of code is unmaintainable.
16+
17+
How does that happen?
18+
19+
Actually, most code start out easy, but over time it becomes harder to
20+
maintain, until it's unmaintainable.
21+
22+
## How to prevent unmaintainable code?
23+
24+
The best way to prevent unmaintainable code is to refactor it before it becomes
25+
unmaintainable.
26+
27+
Developers can make simple things complex, like unmaintainable code, but they
28+
are much better at making complex things simple. Refactoring makes complex code
29+
simple again.
30+
31+
But when to refactor? How much to refactor? What to refactor? That's where Code Limit comes in.
32+
33+
## Meet Code Limit
234

335
Code Limit is a tool for developers with one goal: _it tells the developer when
436
it’s time to refactor_.
537

6-
Code Limit measures the lines of code for each function in your codebase and
7-
assigns each function to a category:
8-
9-
| Easy | Verbose | Hard-to-maintain <span style="color: #e5832f;">&#x26A0;</span> | Unmaintainable <span style="color: #ff0000;">&#x2716;</span> |
10-
| :---: | :---: | :---: | :---: |
11-
| 1 - 15 lines of code | 16 - 30 lines of code | 31 - 60 lines of code | 60+ lines of code |
12-
| ![](assets/easy.png){: style="height:136px;width:230px"} | ![](assets/verbose.png){: style="height:189px;width:230px"} | ![](assets/hard-to-maintain.png){: style="height:294px;width:230px"} | ![](assets/unmaintainable.png){: style="height:564px;width:230px"} |
13-
14-
As the table above shows, functions with more than 60 lines of code (comments
15-
and empty lines are not counted) are _unmaintainable_, and _need_ to be
16-
refactored. Functions with more than 30 lines of code run a risk of turning
17-
into unmaintainable functions over time, you should keep an eye on them and
18-
refactor if possible. Functions in the first two categories are fine and don't
19-
need refactoring.
20-
21-
Function length is just one code metric, but it is a very important code
22-
metric. Short functions are easy to understand, easy to test, easy to re-use.
23-
For example, code duplication is another important code metric but duplication
24-
is much easier to prevent and fix if your functions are short.
25-
26-
<figure markdown>
27-
<div align="center">
28-
<img src="assets/unmaintainable-code.jpg" width="500"/>
29-
<figcaption>Unmaintainable code. Looks easy; should be done in half an hour I reckon <a href="https://twitter.com/KenScambler/status/477322711039893504">[source]</a></figcaption>
30-
</div>
31-
</figure>
32-
33-
Function length is a simple code metric, so simple you can count it by hand.
34-
It's also a (fairly) non-controversial metric, most developers agree longer
35-
functions are harder to maintain. Also, there's always a refactoring possible
36-
to make functions smaller.
37-
38-
Because function length is such a simple code metric, many code quality tools
39-
measure it. But these tools measure a lot more metrics, sometimes so much
40-
metrics that developers are overwhemled and loose focus on the metrics that
41-
matter most.
42-
43-
Code Limit measures only function length but it tries to be the best developer
44-
tool for measuring it. By notifying developers when it's time to refactor, Code
45-
Limit prevents unmaintainable code.
46-
47-
Keep your software maintainable and start using Code Limit today!
38+
### Key features and design principles
39+
40+
* **A non-controversial code metric**: Most developers agree longer functions
41+
are harder to maintain
42+
* **Actionable results**: There's always a refactoring possible to make
43+
functions smaller.
44+
* **Runs everywhere**: Fits your development workflow, whether it's in a build
45+
pipeline, a pre-commit hook, or standalone.
46+
* **Covers many languages**: A single tool for all your projects
47+
* **Sane defaults**: Zero configuration, but allows customization.
48+
49+
*[functions]: Also called methods or procedures, depending on your programming language
50+
51+
## Next steps
52+
53+
Go to the [Getting Started](getting-started/development-workflow.md) section to
54+
start using Code Limit, or read more about the [function length
55+
metric](why-function-length.md).

‎docs/why-function-length.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Why Function Length?
2+
3+
Function length is just one code metric, but it is a very important code
4+
metric. Short functions are easy to understand, easy to test, easy to re-use.
5+
For example, code duplication is another important code metric but duplication
6+
is much easier to prevent and fix if your functions are short.
7+
8+
<figure markdown>
9+
<div align="center">
10+
<img src="../assets/unmaintainable-code.jpg" width="500"/>
11+
<figcaption>Unmaintainable code. Looks easy; should be done in half an hour I reckon <a href="https://twitter.com/KenScambler/status/477322711039893504">[source]</a></figcaption>
12+
</div>
13+
</figure>
14+
15+
Function length is a simple code metric, so simple you can count it by hand.
16+
It's also a (fairly) non-controversial metric, most developers agree longer
17+
functions are harder to maintain. Also, there's always a refactoring possible
18+
to make functions smaller.
19+
20+
## Why Code Limit?
21+
22+
Because function length is such a simple code metric, many code quality tools
23+
measure it. But these tools measure a lot more metrics, sometimes so much
24+
metrics that developers are overwhemled and loose focus on the metrics that
25+
matter most.
26+
27+
Code Limit measures only function length but it tries to be the best developer
28+
tool for measuring it. By notifying developers when it's time to refactor, Code
29+
Limit prevents unmaintainable code.
30+
31+
## How Code Limit measures function length
32+
33+
Code Limit measures the lines of code for each function in your codebase and
34+
assigns each function to a category:
35+
36+
| Easy | Verbose | Hard-to-maintain <span style="color: #e5832f;">&#x26A0;</span> | Unmaintainable <span style="color: #ff0000;">&#x2716;</span> |
37+
| :---: | :---: | :---: | :---: |
38+
| 1 - 15 lines of code | 16 - 30 lines of code | 31 - 60 lines of code | 60+ lines of code |
39+
| ![](assets/easy.png){: style="height:136px;width:230px"} | ![](assets/verbose.png){: style="height:189px;width:230px"} | ![](assets/hard-to-maintain.png){: style="height:294px;width:230px"} | ![](assets/unmaintainable.png){: style="height:564px;width:230px"} |
40+
41+
As the table above shows, functions with more than 60 lines of code (comments
42+
and empty lines are not counted) are _unmaintainable_, and _need_ to be
43+
refactored. Functions with more than 30 lines of code run a risk of turning
44+
into unmaintainable functions over time, you should keep an eye on them and
45+
refactor if possible. Functions in the first two categories are fine and don't
46+
need refactoring.

‎mkdocs.yml

+9-3
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,9 @@ theme:
1717
logo: assets/logo.png
1818
favicon: assets/favicon.png
1919
features:
20-
- toc.integrate
20+
- navigation.tabs
21+
- navigation.tabs.sticky
22+
- navigation.tracking
2123
- navigation.footer
2224
- content.code.copy
2325
extra_css:
@@ -31,11 +33,15 @@ plugins:
3133
shadow: false
3234
- search
3335
markdown_extensions:
36+
- abbr
3437
- attr_list
38+
- pymdownx.snippets
3539
nav:
3640
- 'index.md'
37-
- 'quickstart.md'
38-
- 'usage.md'
41+
- 'why-function-length.md'
42+
- Getting Started:
43+
- 'getting-started/development-workflow.md'
44+
- 'getting-started/standalone-usage.md'
3945
- 'configuration.md'
4046
- 'faq.md'
4147
- 'development.md'

‎poetry.lock

+4-4
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)