Code quality Flashcards
What is a breakpoint in a debugger ?
A breakpoint is a point of code where the debugger will automatically pause the JavaScript execution.
While the code is paused, we can examine current variables, execute commands in the console etc. In other words, we can debug it.
What is debugger command ?
We can also pause the code by using the debugger command in it, like this:
function hello(name) {
let phrase = `Hello, ${name}!`;
debugger; //
What is self descriptive code ?
Sometimes it’s beneficial to replace a code piece with a function, like here:
function showPrimes(n) {
nextPrime:
for (let i = 2; i < n; i++) {
// check if i is a prime number
for (let j = 2; j < i; j++) {
if (i % j == 0) continue nextPrime;
}
alert(i); } } The better variant, with a factored out function isPrime:
function showPrimes(n) {
for (let i = 2; i < n; i++) {
if (!isPrime(i)) continue;
alert(i); } }
function isPrime(n) {
for (let i = 2; i < n; i++) {
if (n % i == 0) return false;
}
return true;
}
Now we can understand the code easily. The function itself becomes the comment. Such code is called self-descriptive.
Is it good to explain the architecture of the code in the comments ?
Describe the architecture
Provide a high-level overview of components, how they interact, what’s the control flow in various situations… In short – the bird’s eye view of the code. There’s a special language UML to build high-level architecture diagrams explaining the code. Definitely worth studying.
What is JSDoc ?
JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You add documentation comments directly to your source code, right alongside the code itself. The JSDoc tool will scan your source code and generate an HTML documentation website for you.
Why it’s important to write comments for “Why is the task solved this way?”
What’s written is important. But what’s not written may be even more important to understand what’s going on. Why is the task solved exactly this way? The code gives no answer.
If there are many ways to solve the task, why this one? Especially when it’s not the most obvious one.
Without such comments the following situation is possible:
You (or your colleague) open the code written some time ago, and see that it’s “suboptimal”.
You think: “How stupid I was then, and how much smarter I’m now”, and rewrite using the “more obvious and correct” variant.
…The urge to rewrite was good. But in the process you see that the “more obvious” solution is actually lacking. You even dimly remember why, because you already tried it long ago. You revert to the correct variant, but the time was wasted.
Comments that explain the solution are very important. They help to continue development the right way.
Why do we need tests?
When we write a function, we can usually imagine what it should do: which parameters give which results.
During development, we can check the function by running it and comparing the outcome with the expected one. For instance, we can do it in the console.
If something is wrong – then we fix the code, run again, check the result – and so on till it works.
But such manual “re-runs” are imperfect.
When testing a code by manual re-runs, it’s easy to miss something.
For instance, we’re creating a function f. Wrote some code, testing: f(1) works, but f(2) doesn’t work. We fix the code and now f(2) works. Looks complete? But we forgot to re-test f(1). That may lead to an error.
That’s very typical. When we develop something, we keep a lot of possible use cases in mind. But it’s hard to expect a programmer to check all of them manually after every change. So it becomes easy to fix one thing and break another one.
Automated testing means that tests are written separately, in addition to the code. They run our functions in various ways and compare results with the expected.
What is behaviour driven development (BDD) ?
BDD is three things in one: tests AND documentation AND examples.
What is a specification or spec in testing ?
in short, a spec, and contains descriptions of use cases together with tests for them, like this:
describe(“pow”, function() {
it(“raises to n-th power”, function() {
assert.equal(pow(2, 3), 8);
});
});
What are the three main building blocks of a spec ? Name only
Describe, it, and assert
What ‘describe’ does in a spec ?
describe(“title”, function() { … })
What functionality we’re describing. In our case we’re describing the function pow. Used to group “workers” – the it blocks.
What ‘it’ does in a spec ?
it(“use case description”, function() { … })
In the title of it we in a human-readable way describe the particular use case, and the second argument is a function that tests it.
What ‘assert’ does in a spec ?
assert.equal(value1, value2)
The code inside it block, if the implementation is correct, should execute without errors.
Functions assert.* are used to check whether pow works as expected. Right here we’re using one of them – assert.equal, it compares arguments and yields an error if they are not equal. Here it checks that the result of pow(2, 3) equals 8.
How to development flow works when we are testing
The flow of development usually looks like this:
An initial spec is written, with tests for the most basic functionality.
An initial implementation is created.
To check whether it works, we run the testing framework Mocha (more details soon) that runs the spec. While the functionality is not complete, errors are displayed. We make corrections until everything works.
Now we have a working initial implementation with tests.
We add more use cases to the spec, probably not yet supported by the implementations. Tests start to fail.
Go to 3, update the implementation till tests give no errors.
Repeat steps 3-6 till the functionality is ready.
So, the development is iterative. We write the spec, implement it, make sure tests pass, then write more tests, make sure they work etc. At the end we have both a working implementation and tests for it.
Let’s see this development flow in our practical case.
The first step is already complete: we have an initial spec for pow. Now, before making the implementation, let’s use few JavaScript libraries to run the tests, just to see that they are working (they will all fail).
What are transpilers ?
A transpiler is a special piece of software that translates source code to another source code. It can parse (“read and understand”) modern code and rewrite it using older syntax constructs, so that it’ll also work in outdated engines.
E.g. JavaScript before year 2020 didn’t have the “nullish coalescing operator” ??. So, if a visitor uses an outdated browser, it may fail to understand the code like height = height ?? 100.
A transpiler would analyze our code and rewrite height ?? 100 into (height !== undefined && height !== null) ? height : 100.
// before running the transpiler height = height ?? 100;
// after running the transpiler height = (height !== undefined && height !== null) ? height : 100; Now the rewritten code is suitable for older JavaScript engines.
Usually, a developer runs the transpiler on their own computer, and then deploys the transpiled code to the server.
Speaking of names, Babel is one of the most prominent transpilers out there.
Modern project build systems, such as webpack, provide means to run transpiler automatically on every code change, so it’s very easy to integrate into development process.
