simplesystems/website
simplesystems/website
1
0
Fork 0
Code Issues 18 Pull Requests Actions Wiki Activity

BlogPost_BooleanNames #22

Merged
jeff merged 12 commits from BlogPost_BooleanNames into master 2020-07-30 22:44:26 +00:00
Conversation 0 Commits 12 Files Changed 6 +15 -10
3 changed files with 15 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit c04869f876 - Show all commits

4
Dockerfile.prod
View File

@ -18,7 +18,7 @@ FROM golang:alpine AS build-webserver
RUN apk update && apk upgrade && \ RUN apk update && apk upgrade && \
apk add --no-cache git apk add --no-cache git
RUN go get -u git.simplesystems.tech/SimpleSystems/static-web-server RUN go get -u git.simplesystems.tech/simplesystems/static-web-server
# STEP 3: Combine static files and binary on fresh alpine image # STEP 3: Combine static files and binary on fresh alpine image
FROM alpine:latest FROM alpine:latest
@ -31,4 +31,4 @@ COPY --from=build-website /src/public /app/public
# Copy over static-web-server # Copy over static-web-server
COPY --from=build-webserver /go/bin/static-web-server /app/ COPY --from=build-webserver /go/bin/static-web-server /app/
ENTRYPOINT ["./static-web-server", "-rootDir", "public", "-port", "80", "-redirect"] ENTRYPOINT ["./static-web-server", "-rootDir", "public", "-port", "80"]

5
README.md
View File

@ -19,6 +19,11 @@ To build the production site, run the following command:
hugo --minify hugo --minify
``` ```
To build the Dockerfile, run this command:
```shell script
docker build --no-cache -f Dockerfile.prod -t docker.simplesystems.tech/simplesystems/website:latest . && docker push docker.simplesystems.tech/simplesystems/website
```
The resources will be stored in the `./public` directory. The resources will be stored in the `./public` directory.
## Managing Job Posts ## Managing Job Posts

16
content/blog/boolean_names.md
View File

@ -6,30 +6,30 @@ pdate: June 50, 2020
desc: Choosing a good boolean variable name desc: Choosing a good boolean variable name
--- ---
Choosing good names for variables is important. They are a form of documentation and can remove [complexity](http://localhost:1313/blog/complexity/) from code. Using a bad name for a variable leads to confusion, bugs, and wasted engineer time. In this blog post I will discuss what makes a [boolean](https://en.wikipedia.org/wiki/Boolean_data_type) variable name good or bad. Choosing good names for variables is an important art for software engineers to master. Variable names are documentation and can remove [complexity](http://localhost:1313/blog/complexity/) from code. Using a bad name for a variable leads to confusion, bugs, and wasted engineer time. In this blog post I will discuss what makes a [boolean](https://en.wikipedia.org/wiki/Boolean_data_type) variable name good or bad.
## Good Boolean Names ## Good Boolean Names
Boolean names should be negatable, and in the positive form. These names should be clear and concise just as all variable names should be. As the scope of the variable increases, it's level of description should increase as well. Boolean names should be [negatable](https://www.yourdictionary.com/negatable) and in the positive form. They should be clear and concise just as all variable names should be. As the scope of the variable increases, it's level of description should increase as well.
The book, _The Elements of Style_ <sup>1</sup>, is a concise guide to writing English. Some rules can be used as a guide for writing code as well. For example, rule 11, "Put statements in positive form," can be applied to naming boolean variables. In code, there is one additional requirement: the statement must be positive as well. 'enabled' is in the positive form and a positive statement. 'disabled' is in the positive form, but is a negative statement. 'notEnabled' is both in the negative form and a negative statement. _The Elements of Style_ <sup>1</sup>, is a concise guide to writing English. Some rules can be used as a guide for writing code as well. For example, rule 11, "Put statements in positive form," can be applied to naming boolean variables. In code, there is one additional requirement: the statement must be positive as well. 'enabled' is in the positive form and a positive statement. 'disabled' is in the positive form, but is a negative statement. 'notEnabled' is both in the negative form and a negative statement.
In English, it is best to use enabled or disabled, and to avoid "not enabled"; they are more concise and stay in the positive form. The extra requirement of using a positive statement for boolean names is because boolean variables' negations have meaning as well; in writing "not disabled" is a double negative and is discouraged. In code, '!disabled', is also a double negative, and should be avoided. In English, it is best to use enabled or disabled, and to avoid "not enabled"; they are more concise and stay in the positive form. The extra requirement of using a positive statement for boolean names is because the negations of boolean variables have meaning as well; in writing "not disabled" is a double negative and is discouraged. In code, '!disabled', is also a double negative, and should be avoided.
A boolean name should give the reader more clarity as it's scope expands. A boolean variable that exists for the scope of an if statement may have a short name ('ok'). If this variable was in scope throughout the function, it would become meaningless. A boolean name should give the reader more clarity as it's scope expands. A boolean variable that exists for the scope of an if statement may have a short name ('ok'). If this variable was in scope throughout the function, it would become meaningless.
## Bad Boolean Names ## Bad Boolean Names
As with many things in software engineering, it is easier to find mistakes than to do something correctly the first time. Here are some naming conventions to avoid: As with many things in software engineering, it is easier to find mistakes than to do something correctly the first time. Here are some naming conventions to avoid:
1. Names that are already a negation. 'notReady' and 'notProd' may make sense in one use case, but becomes confusing in a larger context. This can lead to code such as, `confA.useProd = !confB.notProd`. This is both hard to read and ambiguous (what if there is a third environment). 1. Names that are already a negation. 'featureTurnedOff' and 'notProd' may make sense in one use case, but becomes confusing in a larger context. This can lead to code such as, `confA.useProd = !confB.notProd`. This is both hard to read and ambiguous (what if there is a third environment).
2. Names that are not negatable. A name such as, 'sheets', has ambiguous meaning. It probably has something to do with a spreadsheet, but it is the writer's responsibility to prevent the reader from needing to do an investigation. 2. Names that are not negatable. A name such as, 'sheets', has ambiguous meaning. It probably has something to do with a spreadsheet, but it is the writer's responsibility to prevent the reader from needing to do an investigation.
3. Names that are in negative form. These typically appear when the default use is the negative form. For example, 'disabled' for a service typically disabled. Keep all the names in positive form to avoid a future headache explaining what the billing system does when it's "not disabled". Is it enabled, or is it just not disabled? 3. Names that are in negative form. These typically appear when the default use is the negative form. For example, 'disabled' for a service typically disabled. Keep all the names in positive form to avoid a future headache explaining what the billing system does when it's "not disabled". Is it now enabled, or is it just not disabled?
4. Overly general names. As discussed earlier, this depends on the scope of the name. Avoid using a name such as, 'on'. It leaves questions in the reader's mind such as, "What is on?". The exception to this is typical boolean names used across code bases; Go's 'ok' is an example of this. 4. Overly general names. As discussed earlier, this depends on the scope of the name. Avoid using a name such as, 'on'. It leaves questions in the reader's mind such as, "What thing is on?". The exception to this is typical boolean names used across code bases; Go's 'ok' is an example of this.
5. Negatable adjectives without context. 'bool customSize' is clear, but without the 'bool' context, the type is unclear. Ambiguity can be removed by prefixing 'is' or 'has' ('isCustomSize'). 5. Negatable adjectives without context. 'bool customSize' is clear, but without the 'bool' context, the type is unclear. Ambiguity can be removed by prefixing 'is' or 'has' ('isCustomSize').
## Conclusion ## Conclusion
This blog post discussed a goal to aim at (good names), and several things to avoid (bad names). Combined, these will hopefully increase the readability of your software! This blog post discussed a goal to aim at (good names), and several things to avoid (bad names). Combined, these will hopefully increase the readability of the software you write!
<sup>1</sup> https://tinyurl.com/y3uxhzxc <sup>1</sup> https://tinyurl.com/y3uxhzxc