DEV Community: DeepSource

JavaScript best practices to improve code quality

Saif Sadiq — Mon, 19 Apr 2021 09:58:30 +0000

If you write JavaScript today, it’s worth your time staying in the know of all the updates the language has seen in the past few years. Since 2015, with the release of ES6, a new version of the ECMAScript spec has been released each year. Each iteration adds new features, new syntax, and Quality of Life improvements to the language. JavaScript engines in most browsers and Node.js quickly catch up, and it’s only fair that your code should catch up as well. That’s because with each new iteration of JavaScript comes new idioms and new ways to express your code, and many a time, these changes may make the code more maintainable for you and your collaborators.

Here are some of the latest ECMAScript features, and by induction, JavaScript and Node.js that you can make use of to write cleaner, more concise, and more readable code.

1. Block scored declarations

Since the inception of the language, JavaScript developers have used var to declare variables. The keyword var has its quirks, the most problematic of those being the scope of the variables created by using it.

var x = 10
if (true) { var x = 15 // inner declaration overrides declaration in parent scope
 console.log(x) // prints 15
}
console.log(x) // prints 15

Since variables defined with var are not block-scoped, redefining them in a narrower scope affects the value of the outer scope.

Now we have two new keywords that replace var, namely let and const that do not suffer from this drawback.

let y = 10
if (true) { let y = 15 // inner declaration is scoped within the if block
 console.log(y) // prints 15
}
console.log(y) // prints 10

const and let differ in the semantics that variables declared with const cannot be reassigned in their scope. This does not mean they are immutable, only that their references cannot be changed.

const x = [] x.push("Hello", "World!")
x // ["Hello", "World!"]

x = [] // TypeError: Attempted to assign to readonly property.

2. Arrow functions

Arrow functions are another very important feature introduced recently to JavaScript. They come bearing many advantages. First and foremost, they make the functional aspects of JavaScript beautiful to look at and simpler to write.

let x = [1, 2, 3, 4] x.map(val => val * 2) // [2, 4, 6, 8]
x.filter(val => val % 2 == 0) // [2, 4]
x.reduce((acc, val) => acc + val, 0) // 10

In all of the above examples the arrow functions, named after the distinctive arrow =>, replace traditional functions with a concise syntax.

If the function body is a single expression, the scope brackets {} and return keyword are implied and need not be written.
If the function has a single argument, the argument parentheses () are implied and need not be written.
If the function body expression is a dictionary, it must be enclosed in parentheses ().

Another significant advantage of arrow functions is that they do not define a scope but rather exist within the parent scope. This avoids a lot of pitfalls that can arise with the use of the this keyword. Arrow functions have no bindings for this. Inside the arrow function, the value of this is the same as that in the parent scope. Consequently, arrow functions cannot be used as methods or constructors. Arrow functions don’t work with apply, bind, or call and have no bindings for super.

They also have certain other limitations such as lack of the arguments object which traditional functions can access and the inability to yield from the function body.

Thus arrow functions are not a 1:1 replacement for standard functions but welcome addition to JavaScript’s feature set.

3. Optional chaining

Imagine a deeply nested data structure like this person object here. Consider you wanted to access the first and last name of this person. You would write this in JavaScript like so:

person = { name: { first: 'John', last: 'Doe', }, age: 42
}
person.name.first // 'John'
person.name.last // 'Doe'

Now imagine what would happen if the person object did not contain a nested name object.

person = { age: 42
}
person.name.first // TypeError: Cannot read property 'first' of undefined
person.name.last // TypeError: Cannot read property 'last' of undefined

To avoid such errors, developers had to resort to code like the following, which is unnecessarily verbose, hard to read, and unpleasant to write — a very bad trio of adjectives.

person && person.name && person.name.first // undefined

Meet optional chaining, a new feature of JavaScript that does away with this monstrosity. Optional chaining short-circuits the digging process as soon as it encounters a null or undefined value and returns undefined without raising an error.

person?.name?.first // undefined

The resultant code is much concise and cleaner.

4. Null-ish coalescing

Before introducing the null-ish coalescing operator, JavaScript developers used the OR operator || to fall back to a default value if the input was absent. This came with a significant caveat that even legitimate but falsy values would result in a fallback to the defaults.

function print(val) { return val || 'Missing'
} print(undefined) // 'Missing'
print(null) // 'Missing'

print(0) // 'Missing'
print('') // 'Missing'
print(false) // 'Missing'
print(NaN) // 'Missing'

JavaScript has now proposed the null coalescing operator ??, which offers a better alternative in that it only results in a fallback if the preceding expression is null-ish. Here null-ish refers to values that are null or undefined.

function print(val) { return val ?? 'Missing'
} print(undefined) // 'Missing'
print(null) // 'Missing'

print(0) // 0
print('') // ''
print(false) // false
print(NaN) // NaN

This way, you can ensure that if your program accepts falsy values as legitimate inputs, you won’t end up replacing them with fallbacks.

5. Logical assignment

Let’s say you want to assign a value to a variable if and only if the value is currently null-ish. A logical way to write this would be like so:

if (x === null || x == undefined) { x = y
}

If you knew about how short-circuiting works, you might want to replace those 3 lines of code with a more succinct version using the null-ish coalescing operator.

x ?? (x = y) // x = y if x is nullish, else no effect

Here we use the short-circuiting feature of the null-ish coalescing operator to execute the second part x = y if x is null-ish. The code is pretty concise, but it still is not very easy to read or understand. The logical null-ish assignment does away with the need for such a workaround.

x ??= y // x = y if x is nullish, else no effect

Along the same lines, JavaScript also introduces logical AND assignment &&= and logical OR assignment ||= operators. These operators perform assignment only when the specific condition is met and have no effect otherwise.

x ||= y // x = y if x is falsy, else no effect
x &&= y // x = y if x is truthy, else no effect

Pro-tip: If you’ve written Ruby before, you’ve seen the ||= and &&= operators, since Ruby does not have the concept of falsy values.

6. Named capture groups

Let’s start with a quick recap of capture groups in regular expressions. A capture group is a part of the string that matches a portion of regex in parentheses.

let re = /(\d{4})-(\d{2})-(\d{2})/
let result = re.exec('Pi day this year falls on 2021-03-14!') result[0] // '2020-03-14', the complete match
result[1] // '2020', the first capture group
result[2] // '03', the second capture group
result[3] // '14', the third capture group

Regular expressions have also supported named capture groups for quite some time, which is a way for the capture groups to be referenced by a name rather than an index. Now, with ES9, this feature has made its way to JavaScript. Now the result object contains a nested groups object where each capture group’s value is mapped to its name.

let re = /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/
let result = re.exec('Pi day this year falls on 2021-03-14!') result.groups.year // '2020', the group named 'year'
result.groups.month // '03', the group named 'month'
result.groups.day // '14', the group named 'day'

The new API works beautifully with another new JavaScript feature, de-structured assignments.

let re = /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/
let result = re.exec('Pi day this year falls on 2021-03-14!')
let { year, month, day } = result.groups year // '2020'
month // '03'
day // '14'

7. `async` & `await`

One of the powerful aspects of JavaScript is its asynchronicity. This means that many functions that may be long-running or time-consuming can return a Promise and not block execution.

const url = 'https://the-one-api.dev/v2/book'
let prom = fetch(url)
prom // Promise {<pending>}

// wait a bit
prom // Promise {<fullfilled>: Response}, if no errors
// or
prom // Promise {<rejected>: Error message}, if any error

Here the call to fetch returns a Promise that has the status ‘pending’ when created. Soon, when the API returns the response, it transitions into a ‘fulfilled’ state, and the Response that it wraps can be accessed. In the Promises world, you would do something like this to make an API call and parse the response as JSON.

const url = 'https://the-one-api.dev/v2/book'
let prom = fetch(url)
prom // Promise {<fullfilled>: Response}
 .then(res => res.json()) .then(json => console.log(json)) // prints response, if no errors
 .catch(err => console.log(err)) // prints error message, if any error

In 2017, JavaScript announced two new keywords async and await, that make handling and working with Promises easier and more fluent. They are not a replacement for Promises; they are merely syntactic sugar on top of the powerful Promises concepts.

Instead of all the code happening inside a series of ‘then’ functions, await makes it all look like synchronous JavaScript. As an added benefit, you can use try...catch with await instead of handling errors in ‘catch’ functions as you would have to if consuming Promises directly. The same code with await would look like this.

const url = 'https://the-one-api.dev/v2/book'
let res = await fetch(url) // Promise {<fullfilled>: Response} -await-> Response
try { let json = await res.json() console.log(json) // prints response, if no errors
} catch(err) { console.log(err) // prints error message, if any error
}

The async keyword is the other side of the same coin, in that it wraps any data to be sent within a Promise. Consider the following asynchronous function for adding several numbers. In the real world, your code would be doing something much more complicated.

async function sum(...nums) { return nums.reduce((agg, val) => agg + val, 0)
} sum(1, 2, 3) // Promise {<fulfilled>: 6}
 .then(res => console.log(res) // prints 6

let res = await sum(1, 2, 3) // Promise {<fulfilled>: 6} -await-> 6
console.log(res) // prints 6

These new features just the tip of the iceberg. We have barely even scratched the surface. JavaScript is constantly evolving, and new features are added to the language every year. It’s tough to keep up with the constant barrage of new features and idioms introduced to the language manually.

Wouldn’t it be nice if some tool could handle this for us? Fret not, there is. We’ve already talked in detail about setting up static code analysis in your JavaScript repo using ESLint. It’s extremely useful and should be an indispensable tool of your toolchain. But to be honest, setting up ESLint auto-fix pipelines and processes takes time and effort. Unless you enjoy this sort of plumbing, you’d be better off if you wrote the code and outsourced the plumbing to…DeepSource!

DeepSource can help you with automating the code reviews and save you a ton of time. Just add a .deepsource.toml file in the root of the repository and DeepSource will pick it up for scanning right away. The scan will find scope for improvements across your code and help you fix them with helpful descriptions.

Originally published on DeepSource Blog.

Guidelines for Java code reviews

Saif Sadiq — Mon, 12 Apr 2021 05:57:10 +0000

Having another pair of eyes scan your code is always useful and helps you spot mistakes before you break production. You need not be an expert to review someone’s code. Some experience with the programming language and a review checklist should help you get started. We’ve put together a list of things you should keep in mind when you’re reviewing Java code. Read on!

1. Follow Java code conventions

Following language conventions helps quickly skim through the code and make sense of it, thereby improving readability. For instance, all package names in Java are written in lowercase, constants in all caps, variable names in CamelCase, etc. Find the complete list of conventions here.

Some teams develop their own conventions, so be flexible in such cases!

2. Replace imperative code with lambdas and streams

If you’re using Java 8+, replacing loops and extremely verbose methods with streams and lambdas makes the code look cleaner. Lambdas and streams allow you to write functional code in Java. The following snippet filters odd numbers in the traditional imperative way:

List<Integer> oddNumbers = new ArrayList<>();
for (Integer number : Arrays.asList(1, 2, 3, 4, 5, 6)) {
    if (number % 2 != 0) {
      oddNumbers.add(number);
  }
}

This is the functional way of filtering odd numbers:

List<Integer> oddNumbers = Stream.of(1, 2, 3, 4, 5, 6)
  .filter(number -> number % 2 != 0)
  .collect(Collectors.toList());

3. Beware of the `NullPointerException`

When writing new methods, try to avoid returning nulls if possible. It could lead to null pointer exceptions. In the snippet below, the highest method returns a null if the list has no integers.

class Items {
    private final List<Integer> items;
    public Items(List<Integer> items) {
            this.items = items;
    }
    public Integer highest() {
      if (items.isEmpty()) return null;
      Integer highest = null;
      for (Integer item : items) {
          if (items.indexOf(item) == 0) highest = item;
          else highest = highest > item ? highest : item;
      }
      return highest;
    }
}

Before directly calling a method on an object I recommend checking for nulls as shown below.

Items items = new Items(Collections.emptyList());
Integer item = items.highest();
boolean isEven = item % 2 == 0; // throws NullPointerException ❌
boolean isEven = item != null && item % 2 == 0 // ✅

It can be pretty cumbersome to have null checks everywhere in your code though. If you are using Java 8+, consider using the Optional class to represent values that may not have valid states. It allows you to easily define alternate behavior and is useful for chaining methods.

In the snippet below, we are using Java Stream API to find the highest number with a method which returns an Optional. Note that we are using Stream.reduce, which returns an Optional value.

public Optional<Integer> highest() {
    return items
            .stream()
            .reduce((integer, integer2) -> 
                            integer > integer2 ? integer : integer2);
}
Items items = new Items(Collections.emptyList());
items.highest().ifPresent(integer -> {             // ✅
    boolean isEven = integer % 2 == 0;
});

Alternatively, you could also use annotations such as @Nullable or @NonNull which will result in warnings if there is a null conflict while building the code. For instance, passing a @Nullable argument to a method that accepts @NonNull parameters.

4. Directly assigning references from client code to a field

References exposed to the client code can be manipulated even if the field is final. Let’s understand this better with an example.

private final List<Integer> items;
public Items(List<Integer> items) {
        this.items = items;
}

In the above snippet, we directly assign a reference from the client code to a field. The client can easily mutate the contents of the list and manipulate our code as shown below.

List<Integer> numbers = new ArrayList<>();
Items items = new Items(numbers);
numbers.add(1); // This will change how items behaves as well

Instead, consider cloning the reference or creating a new reference and then assigning it to the field as shown below:

private final List<Integer> items;
public Items(List<Integer> items) {
    this.items = new ArrayList<>(items);
}
}

The same rule applies while returning references. You need to be cautious so as not to expose internal mutable state.

5. Handle exceptions with care

While catching exceptions, if you have multiple catch blocks, ensure that the sequence of catch blocks is most specific to least. In the snippet below, the exception will never be caught in the second block since the Exception class is the mother of all exceptions.

try {
    stack.pop();
} catch (Exception exception) {
    // handle exception
} catch (StackEmptyException exception) {
    // handle exception
}

If the situation is recoverable and can be handled by the client (the consumer of your library or code) then it is good to use checked exceptions. e. g. IOException is a checked exception that forces the client to handle the scenario and in case the client chooses to re-throw the exception then it should be a conscious call to disregard the exception.

6. Ponder over the choice of data structures

Java collections provide ArrayList, LinkedList, Vector, Stack, HashSet, HashMap, Hashtable. It’s important to understand the pros and cons of each to use them in the correct context. A few hints to help you make the right choice:

Map: Useful if you have unordered items in the form of key, value pairs and require efficient retrieval, insertion, and deletion operations. HashMap, Hashtable, LinkedHashMap are all implementations of the Map interface.
List: Very commonly used to create an ordered list of items. This list may contain duplicates. ArrayList is an implementation of the List interface. A list can be made thread-safe using Collections.synchronizedList thus removing the need for using Vector. Here’s some more info on why Vector is essentially obsolete.
Set: Similar to list but does not allow duplicates. HashSet implements the Set interface.

7. Think twice before you expose

There are quite a few access modifiers to choose from in Java — public, protected, private. Unless you want to expose a method to the client code, you might want to keep everything private by default. Once you expose an API, there’s no going back.

For instance, you have a class Library that has the following method to checkout a book by name:

public checkout(String bookName) {
    Book book = searchByTitle(availableBooks, bookName);
  availableBooks.remove(book);
  checkedOutBooks.add(book);
}

private searchByTitle(List<Book> availableBooks, String bookName) {
...
}

If you do not keep the searchByTitle method private by default and it ends up being exposed, other classes could start using it and building logic on top of it that you may have wanted to be part of the Library class. It could break the encapsulation of the Library class or it may be impossible to revert/modify later without breaking someone else’s code. Expose consciously!

8. Code to interfaces

If you have concrete implementations of certain interfaces (e. g. ArrayList or LinkedList) and if you use them directly in your code, then it can lead to high coupling. Sticking with the List interface enables you to switch over the implementation any time in the future without breaking any code.

public Bill(Printer printer) {
    this.printer = printer;
}

new Bill(new ConsolePrinter());
new Bill(new HTMLPrinter());

In the above snippet, using the Printer interface allows the developer to move to another concrete class HTMLPrinter.

9. Don’t force fit interfaces

Take a look at the following interface:

interface BookService {
        List<Book> fetchBooks();
    void saveBooks(List<Book> books);
    void order(OrderDetails orderDetails) throws BookNotFoundException, BookUnavailableException;   
}

class BookServiceImpl implements BookService {
...

Is there a benefit of creating such an interface? Is there a scope for this interface being implemented by another class? Is this interface generic enough to be implemented by another class? If the answer to all these questions is no, then I’d definitely recommend avoiding this unnecessary interface that you’ll have to maintain in the future. Martin Fowler explains this really well in his blog.

Well then, what’s a good use case for an interface? Let’s say we have a class Rectangle and a class Circle that has behavior to calculate perimeter. If there is a requirement, to sum up, the perimeter of all shapes — a use case for polymorphism, then having the interface would make more sense, as shown below.

interface Shape {
        Double perimeter();
}

class Rectangle implements Shape {
//data members and constructors
    @Override
    public Double perimeter() {
        return 2 * (this.length + this.breadth);
    }
}

class Circle implements Shape {
//data members and constructors
    @Override
    public Double perimeter() {
        return 2 * Math.PI * (this.radius);
    }
}

public double totalPerimeter(List<Shape> shapes) {
    return shapes.stream()
               .map(Shape::perimeter)
               .reduce((a, b) -> Double.sum(a, b))
               .orElseGet(() -> (double) 0);
}

10. Override hashCode when overriding equals

Objects that are equal because of their values are called value objects. e. g. money, time. Such classes must override the equals method to return true if the values are the same. The equals method is usually used by other libraries for comparison and equality checks; hence overriding equals is necessary. Each Java object also has a hash code value that differentiates it from another object.

class Coin {
    private final int value;

    Coin(int value) {
        this.value = value;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Coin coin = (Coin) o;
        return value == coin.value;
    }
}

In the above example, we have overridden only the equals method of Object.

HashMap<Coin, Integer> coinCount = new HashMap<Coin, Integer>() {{
  put(new Coin(1), 5);
  put(new Coin(5), 2);
}};

//update count for 1 rupee coin
coinCount.put(new Coin(1), 7);

coinCount.size(); // 3 🤯 why?

We would expect coinCount to update the number of 1 rupee coins to 7 since we override equals. But HashMap internally checks if the hash code for 2 objects is equal and only then proceeds to test equality via the equals method. Two different objects may or may not have the same hash code but two equal objects must always have the same hash code, as defined by the contract of the hashCode method. So checking for hash code first is an early exit condition. This implies that both equals and hashCode methods must be overridden to express equality.

If you write or review Java code, DeepSource can help you with automating the code reviews and save you a ton of time. Just add a .deepsource.toml file in the root of the repository and DeepSource will pick it up for scanning right away. The scan will find scope for improvements across your code and help you fix them with helpful descriptions.

Python code review checklist

Saif Sadiq — Tue, 30 Mar 2021 13:22:22 +0000

As developers, we are all too familiar with code reviews. Having another pair of eyes take a look at our code can be wonderful; it shows us so many aspects of our code we would not have noticed otherwise. A code review can be informative, and it can be educational. I can confidently attribute most of what I know about good programming practices to code reviews.

The amount of learning a reviewee takes away from a code review depends on how well the review is performed. It thus falls on the reviewer to make their review count by packing the most lessons into the review as possible.

This is a guide on some vital aspects of the code you should be checking in your reviews, the expectations you should have from those checks, and some ideas on how tooling (such as linters, formatters, and test suites) can help streamline the process.

Code review checklist

We have formulated this guide in the form of a checklist. It lists a set of questions that you need to ask about the code. If the answer to any of them is not a ‘yes’, you should leave a remark on the PR.

Do note that this list is only meant to serve as a guideline. Your codebase, like every codebase, has its own specific set of needs, so feel free to build upon this guide and override pieces of it that do not fit well for your use-cases.

Etiquettes

The first and foremost thing to check during a review is how closely the PR adheres to basic etiquettes. Good PRs are composed of bite-sized changes and solve a single well-defined problem. They should be focused and purposefully narrow to have as few merge conflicts as possible. Put simply, a good PR facilitates being reviewed.

For large-scale swooping changes, make a separate target branch and then make small incremental PRs to that target, finally merging the target with the main branch. Making one humongous PR makes it harder to review, and if it goes stale, many merge conflicts may pop up.

When reviewing PRs from new developers, I also make it a point to ensure their commit messages are well-written.

Checklist:

Is the PR atomic?
Does the PR follow the single concern principle?
Are the commit messages well-written?

Ideas:

Enforce a commit message format in the team. For example, you could try gitmoji wherein you use emoji in commit messages. For example, bugfixes should start with [FIX], or the 🐛 emoji and new features should start with [FEAT] or the ✨ emoji. This makes the intention of the commit very clear.

Functionality and syntax

The next thing to check is whether the PR is effective in that it works. Code changed by the PR should work as expected. A bug fix should solve the bug it was supposed to fix. A feature should provide the additional functionality that was required without breaking something else.

An important thing to keep in mind is that any new feature added by a PR is justified. A simple way to ensure this is to accept only the PRs that are associated with an already triaged issue. This practice minimizes feature-creep.

Checklist:

Does the PR work?
Does the new feature add value or is it a sign of feature-creep?
Does the PR add test-cases for the modified code?

Ideas:

Having comprehensive tests in the code makes it easier to check that new functionality works and harder for PRs to break existing stuff. The portion of the code covered should never go down in a PR. Any new code should come with complete coverage in unit/functional tests. Python comes with a robust unit testing framework built into the language itself. You should make use of it in your codebase.

Design

Once we’ve established that the code works, the next step is to check how well it integrates with the existing codebase. One key thing to inspect in this regard is duplication. Often, code added to a repo provides functionality that might already be a part of the code in a different location or something provided by the frameworks or Pip packages in use. This knowledge is something that one can only gain by experience. As a senior, it becomes your duty to point such duplication out to new developers contributing to your repo.

Attention to paradigms is also essential. Many projects have pre-adopted design paradigms such as microservices, mono repo, or cloud-nativity. Any incoming code should be in line with these paradigms.

Checklist:

Is the code properly planned and designed?
Will the code work well with the existing code and not increase duplication?
Is the code well organised in terms of placement of components?

Patterns and idioms

Python is a very mature language. It is driven based on certain philosophies, described as the Zen of Python. Those philosophies have given birth to many conventions and idioms that new code is expected to follow.

The difference between idiomatic and non-idiomatic code is very subtle, and in most cases, can only be intuitively gauged. As with all things honed by experience, intuition must be transferred from experienced people, like yourself, to newbies like your reviewees.

Checklist:

Does the code keep with the idioms and code patterns of the language?
Does the code make use of the language features and standard libraries?

Ideas:

Most linters, popularly PyLint, can help you identify deviations from the style guides and, in most cases, even automatically fix them. Linters work incredibly fast and can make corrections to the code in real-time, making them a valuable addition to your toolchain.

Readability

Python is widely regarded as a very readable language. Python’s simplicity of syntax and reduced usage of punctuation contribute heavily to its readability. It only makes sense for code written in the language to be readable as well.

Checklist:

Is the code clear and concise?
Does it comply with PEP-8?
Are all language and project conventions followed?
Are identifiers given meaningful and style guide-compliant names?

Ideas:

A good code formatter like Black can help a lot in formatting the code for consistency and readability. Black also offers minimal customization, which is good because it eliminates all forms of bikeshedding.

We’ve previously talked about integrating Black into your CI pipeline can work wonders during a code review.

Documentation and maintainability

The next thing to check is the maintainability of the code. Any code added or changed by the PR should be written to facilitate someone other than the original author to maintain it.

It should preferably be self-documenting, which means written in a way that anyone reading the code may be able to understand what it does. This is one of the hallmarks of good Python code. If the code has to be complex by design, it should be amply documented. In an ideal world, all classes and functions would have Python docstrings, complete with examples.

Checklist:

Is the code self-documenting or well-documented?
Is the code free of obfuscation and unnecessary complexity?
Is the control flow and component relationship clear to understand?

Ideas:

Sphinx is a documentation generator that exports beautiful documentation from Python docstrings. The exported documentation can then be uploaded to ReadTheDocs, a popular doc-hosting tool. Sphinx is one of the main reasons why I absolutely love writing documentation.

Security

Ensuring that the application remains secure is critical. The next thing to check is if the PR maintains or improves the security of the project. You need to ensure that the changes do not increase the attack surface area or expose vulnerabilities. If the PR adds new dependencies, they could potentially be unsafe, in which case you might need to check the version for known exploits and update the dependencies, if necessary.

Checklist:

Is the code free of implementation bugs that could be exploited?
Have all the new dependencies been audited for vulnerabilities?

Ideas:

One of the renowned security analyzers for Python is Bandit. Also, if you use GitHub for hosting code, you should absolutely read this guide about setting up vulnerability detection and Dependabot for your codebase.

Once you set up vulnerability detection on GitHub, you’ll get notifications like this…

… with details about the vulnerability and PRs in your repositories that you can merge to patch them.

We’ve also recently talked about common security pitfalls in Python development and how you can secure your projects against them.

Performance, reliability and scalability

The final things to check are the performance and reliability of the code at scale. While these are undoubtedly key metrics, I put them on the bottom of the checklist because I believe well-planned, well-designed, and well-written code generally works well too.

Checklist:

Is the code optimised for in terms of time and space complexity?
Does it scale as per the need?
Does it have instrumentation like reporting for metrics and alerting for failures?

Ideas:

An excellent way to have add some reliability to Python is to use type hinting and static type checking that can provide hints into possible errors before runtime. Python new native support for type-hints is primarily inspired by the Mypy syntax, which can be incrementally adopted in existing projects.

DeepSource

DeepSource is an automated code review tool that manages the end-to-end code scanning process and automatically makes pull requests with fixes whenever new commits are pushed or new pull requests.

Setting up DeepSource for Python is a quick, easy, no-fuss process. Just add a .deepsource.toml file in the root of the repo, and immediately DeepSource will pick it up for scanning. The scan will find scope for improvements across your codebase, make those improvements, and open pull requests for the changes it finds. I was blown away by the simplicity of the setup and the efficacy of their self-built code engine.

🙋‍♂️ Trivia: Did you know that DeepSource holds the distinction of being on OWASP’s curated list of source code analysis tools for Python?

The ideal code review

Returning to my point about code reviews being educational and informative, I would also like to add that code reviews are time-consuming and resource-intensive. While each review takes time, the more in-depth and comprehensive ones consume even more.

So each review must be as productive as possible. This is where all the tooling and automation efforts should be directed. By automating whatever can be automated, which is generally the mundane parts of the review, such as code style and formatting, we can allow devs to focus on the important stuff like architecture, design, and scalability.

I’ll leave you with a profound thought my mentor shared with me.

A good code review not only improves the code but the coder as well.

Common anti-patterns in Go

Saif Sadiq — Wed, 24 Mar 2021 06:05:42 +0000

It has been widely acknowledged that coding is an art, and like every artisan who crafts wonderful art and is proud of them, we as developers are also really proud of the code we write. In order to achieve the best results, artists constantly keep searching for ways and tools to improve their craft. Similarly, we as developers keep levelling up our skills and remain curious to know the answer to the single most important question - “How to write good code”. 🤯

Frederick P. Brooks in his book “ The Mythical Man Month: Essays on Software Engineering ” wrote :

“The programmer, like the poet, works only slightly removed from pure thought-stuff. He builds his castles in the air, from air, creating by exertion of the imagination. Few media of creation are so flexible, so easy to polish and rework, so readily capable of realizing grand conceptual structures.

Image source: https://xkcd.com/844/

This post tries to explore answers to the big question mark in the comic above. The simplest way to write good code is to abstain from including anti-patterns in the code we write.😇

What are anti-patterns? 🤔

Anti-patterns occur when code is written without taking future considerations into account. Anti-patterns might initially appear to be an appropriate solution to the problem, but, in reality, as the codebase scales, these come out to be obscure and add ‘technical debt’ to our codebase.

A simple example of an anti-pattern is to write an API without considering how the consumers of the API might use it, as explained in example 1 below. Being aware of anti-patterns and consciously avoid using them while programming is surely a major step towards a more readable and maintainable codebase. In this post, let’s take a look at a few commonly seen anti-patterns in Go.

1. Returning value of unexported type from an exported function

In Go, to export any field or variable we need to make sure that its name starts with an uppercase letter. The motivation behind exporting them is to make them visible to other packages. For example, if we want to use the Pi function from math package, we should address it as math.Pi . Using math.pi won’t work and will error out.

Names (struct fields, functions, variables) that start with a lowercase letter are unexported, and are only visible inside the package they are defined in.

An exported function or method returning a value of an unexported type may be frustrating to use since callers of that function from other packages will have to define a type again to use it.

// Bad practice
type unexportedType string
func ExportedFunc() unexportedType { return unexportedType("some string")
} // Recommended
type ExportedType string
func ExportedFunc() ExportedType { return ExportedType("some string")
}

2. Unnecessary use of blank identifier

In various cases, assigning value to a blank identifier is not needed and is unnecessary. In case of using the blank identifier in for loop, the Go specification mentions :

If the last iteration variable is the blank identifier, the range clause is equivalent to the same clause without that identifier.

// Bad practice
for _ = range sequence
{ run()
} x, _ := someMap[key] _ = <-ch // Recommended
for range something
{ run()
} x := someMap[key] <-ch

3. Using loop/multiple `append`s to concatenate two slices

When appending multiple slices into one, there is no need to iterate over the slice and append each element one by one. Rather, it is much better and efficient to do that in a single append statement.

As an example, the below snippet does concatenation by appending elements one by one through iterating over sliceTwo.

for _, v := range sliceTwo { sliceOne = append(sliceOne, v)
}

But, since we know that append is a variadic function and thus, it can be invoked with zero or more arguments. Therefore, the above example can be re-written in a much simpler way by using only one append function call like this:

sliceOne = append(sliceOne, sliceTwo…)

4. Redundant arguments in `make` calls

The make function is a special built-in function used to allocate and initialize an object of type map, slice, or chan. For initializing a slice using make, we have to supply the type of slice, the length of the slice, and the capacity of the slice as arguments. In the case of initializing a map using make, we need to pass the size of the map as an argument.

make, however, already has default values for those arguments:

For channels, the buffer capacity defaults to zero (unbuffered).
For maps, the size allocated defaults to a small starting size.
For slices, the capacity defaults to the length if capacity is omitted.

Therefore,

ch = make(chan int, 0)
sl = make([]int, 1, 1)

can be rewritten as:

ch = make(chan int)
sl = make([]int, 1)

However, using named constants with channels is not considered as an anti-pattern, for the purposes of debugging, or accommodating math, or platform-specific code.

const c = 0
ch = make(chan int, c) // Not an anti-pattern

5. Useless `return` in functions

It is not considered good practice to put a return statement as the final statement in functions that do not have a value to return.

// Useless return, not recommended
func alwaysPrintFoofoo() { fmt.Println("foofoo") return
} // Recommended
func alwaysPrintFoo() { fmt.Println("foofoo")
}

Named returns should not be confused with useless returns, however. The return statement below really returns a value.

func printAndReturnFoofoo() (foofoo string) { foofoo := "foofoo" fmt.Println(foofoo) return
}

6. Useless `break` statements in `switch`

In Go, switch statements do not have automatic fallthrough. In programming languages like C, the execution falls into the next case if the previous case lacks the break statement. But, it is commonly found that fallthrough in switch-case is used very rarely and mostly causes bugs. Thus, many modern programming languages, including Go, changed this logic to never fallthrough the cases by default.

Therefore, it is not required to have a break statement as the final statement in a case block of switch statements. Both the examples below act the same.

Bad pattern:

switch s {
case 1: fmt.Println("case one") break
case 2: fmt.Println("case two")
}

Good pattern:

switch s {
case 1: fmt.Println("case one")
case 2: fmt.Println("case two")
}

However, for implementing fallthrough in switch statements in Go, we can use the fallthrough statement. As an example, the code snippet given below will print 23.

switch 2 {
case 1: fmt.Print("1") fallthrough
case 2: fmt.Print("2") fallthrough
case 3: fmt.Print("3")
}

7. Not using helper functions for common tasks

Certain functions, for a particular set of arguments, have shorthands that can be used instead to improve efficiency and better understanding/readability.

For example, in Go, to wait for multiple goroutines to finish, we can use a sync.WaitGroup. Instead of incrementing a sync.WaitGroup counter by 1 and then adding -1 to it in order to bring the value of the counter to 0 and in order to signify that all the goroutines have been executed :

wg.Add(1) // ...some code
wg.Add(-1)

It is easier and more understandable to use wg.Done() helper function which itself notifies the sync.WaitGroup about the completion of all goroutines without our need to manually bring the counter to 0.

wg.Add(1)
// ...some code
wg.Done()

8. Redundant `nil` checks on slices

The length of a nil slice evaluates to zero. Hence, there is no need to check whether a slice is nil or not, before calculating its length.

For example, the nil check below is not necessary.

if x != nil && len(x) != 0 { // do something
}

The above code could omit the nil check as shown below:

if len(x) != 0 { // do something
}

9. Too complex function literals

Function literals that only call a single function can be removed without making any other changes to the value of the inner function, as they are redundant. Instead, the inner function that is being called inside the outer function should be called.

For example:

fn := func(x int, y int) int { return add(x, y) }

Can be simplified as:

10. Using `select` statement with a single case

The select statement lets a goroutine wait on multiple communication operations. But, if there is only a single operation/case, we don’t actually require select statement for that. A simple send or receive operation will help in that case. If we intend to handle the case to try a send or receive without blocking, it is recommended to add a default case to make the select statement non-blocking.

// Bad pattern
select {
case x := <-ch: fmt.Println(x)
} // Recommended
x := <-ch
fmt.Println(x)

Using default:

select {
case x := <-ch: fmt.Println(x)
default: fmt.Println("default")
}

11. context.Context should be the first param of the function

The context.Context should be the first parameter, typically named ctx. ctx should be a (very) common argument for many functions in a Go code, and since it’s logically better to put the common arguments at the first or the last of the arguments list. Why? It helps us to remember to include that argument due to a uniform pattern of its usage. In Go, as the variadic variables may only be the last in the list of arguments, it is hence advised to keep context.Context as the first parameter. Various projects like even Node.js have some conventions like error first callback. Thus, it’s a convention that context.Context should always be the first parameter of a function.

// Bad practice
func badPatternFunc(k favContextKey, ctx context.Context) { 
    // do something
}

// Recommended
func goodPatternFunc(ctx context.Context, k favContextKey) {    
    // do something
}

When it comes to working in a team, reviewing other people’s code becomes important. DeepSource is an automated code review tool that manages the end-to-end code scanning process and automatically makes pull requests with fixes whenever new commits are pushed or new pull requests.

Setting up DeepSource for Go is extremely easy. As soon as you have it set up, an initial scan will be performed on your entire codebase, find scope for improvements, fix them, and open pull requests for those changes.

go build

Breaking builds, baseball bats, and the code quality DNA

Saif Sadiq — Mon, 15 Mar 2021 13:07:43 +0000

“What’s the biggest set of items in terms of tech debt. I can attack it, scope it into the code quality sprints and then start incrementally evolving” - Badri elaborated.

In Good Code Podcast, we talk to experienced developers and technical leaders about the art and science of writing good code and building software. In episode 5, we talk to Badri Rajasekar, who has spent almost 20 years building software and is currently the founder and CEO of Jamm - a rapidly growing video collaboration app.

The Microsoft executive who alarmed everyone with a baseball bat

While speaking about code quality and code review processes, Badri shared an incident from his initial days at Microsoft, when somebody broke the Windows Build and had hundreds of developers waiting for it to get fixed. Soon enough, a Microsoft executive stormed into the office with a baseball bat shouting “Who broke the build?”

With this hilarious (not at the time 😅) incident, Badri expounded on how code quality reviews have evolved over the past decade. Earlier, with strongly typed languages and no automation in place, errors could easily become blunders. Today, with the introduction of automated code reviews, various tooling, microservices, the concept of nightlies, and continuous integrations, there’s much more tolerance for both errors and blunders.

Quick Read: Code Review Best Practices

The flip side: With the flexibility that these modern processes offer, it becomes even more critical to be careful in order to ensure code quality at every step of the way.

In Badri’s words:

It’s just as possible for organizations in this era of continuous delivery to ship a lot of buggy code.

The takeaway: It’s extremely important to be structured around automation testing.

Slow down today and move 10X faster tomorrow onwards

While talking about how inexperienced developers or new startups that don’t bother about integration testing for the sake of quick deployments, end up accumulating a lot of tech debt before they realize it, Badri shared another example of a rapidly growing startup that couldn’t slow down, hence making the problem worse for itself every day.

Badri’s advice for situations like this - get as organized as possible, and try to not fix everything in one shot.

Have a strong process around all of your basic unit tests. Integration tests have to pass before a pull request gets merged in. Eg. Don’t submit a PR until the integration tests have passed. Be firm - either the tests have to pass or if they’re not passing, you’ve got to fix the test.

The key is to introduce code quality into the DNA of the company and encourage everyone on the team to think of it as an integral part of the process, and not rely on QA teams or site reliability engineers. Badri also shared his insights on how to do this — introducing quality sprints, having regular performance checks, taking care of the meta-questions, and maintaining documentation.

He spoke about his time at TokBox and how they used to manage the code quality. They used to have a unified framework for instrumenting everything from platform health to analytics. They also made it fun by introducing the “Load Time Lama” - a fanciful creature who encouraged everyone to take care of the loading times.

Pro Tip: Avoid premature optimization of architecture, as you’ll miss out on crucial problems that haven’t cropped up since you haven’t seen scale yet.

The similarity between pilots and programmers

Badri drew an analogy between pilots and programmers while explaining how to steer through massive amounts of data. When flying an airplane, a pilot majorly looks at a couple of indicators — the airspeed indicator, altimeter, heading indicator, etc. And when one of such indicators indicates a warning, only then he delves deeper into the issues.

Similarly, while having analytics and continuous testing are critical, developers should not get lost in the data that accumulates over time. The way out is to simply stick to the basics. Have a “four-metric dashboard” that defines the code quality benchmarks for a team.

At the same time, practicing causality where you reverse engineer the issues, rather than looking at a sea of graphs, makes it easier to figure out causal patterns.

The conversation wrapped up with golden advice:

Golden Advice: Keep your architecture simple!

Badri advocated the KISS (keep it simple silly) principle when it comes to architectures. This improves scalability and helps with faster resolution of unforeseen problems, because these are easy to reason about.

After a lot of anecdotes, jokes, advisements, and laughter, the chat concluded.

Interested in listening to the entire conversation?

Listen to the podcast here.

Stay tuned for the next episode of the Good Code Podcast!

5 Common mistakes in Go

Saif Sadiq — Mon, 08 Mar 2021 06:49:22 +0000

Bug-risks are issues in code that can cause errors and breakages in production. A bug is a flaw in the code that produces undesired or incorrect results. Code often has bug-risks due to poor coding practices, lack of version control, miscommunication of requirements, unrealistic time schedules for development, and buggy third-party tools. In this post, let’s take a look at a few commonly seen bug-risks in Go.

1. Infinite recursive call

A function that calls itself recursively needs to have an exit condition. Otherwise, it will recurse forever until the system runs out of memory.

This issue can be caused by common mistakes such as forgetting to add an exit condition. It can also happen “on purpose.” Some languages have tail-call optimization, which makes certain infinite recursive calls safe to use. Tail-call optimization allows you to avoid allocating a new stack frame for a function because the calling function will return the value that it gets from the called function. The most common use is tail-recursion, where a recursive function written to take advantage of tail-call optimization can use constant stack space. Go, however, does not implement tail-call optimization, and you will eventually run out of memory. However, this problem doesn’t apply to spawning new goroutines.

Recommended reading: Why is a Goroutine’s stack infinite ?

2. Assignment to `nil` map

A map needs to be initialized using the make function (or a map literal) before you can add any elements. A new, empty map value is made using the built-in function make, which takes the map type and an optional capacity hint as arguments:

make(map[string]int)
make(map[string]int, 100)

The initial capacity does not bound its size: maps grow to accommodate the number of items stored in them, with the exception of nil maps. A nil map is equivalent to an empty map except that no elements may be added.

Bad pattern:

var countedData map[string][]ChartElement

Good pattern:

countedData := make(map[string][]ChartElement)

Recommended reading: Go: assignment to entry in nil map

3. Method modifies receiver

A method that modifies a non-pointer receiver value may have unwanted consequences. This is a bug risk because the method may change the value of the receiver inside the method, but it won’t reflect in the original value. To propagate the change, the receiver must be a pointer.

For example:

type data struct { num int key *string items map[string]bool
} func (d data) vmethod() { d.num = 8
} func (d data) run() { d.vmethod() fmt.Printf("%+v", d) // Output: {num:1 key:0xc0000961e0 items:map[1:true]}
}

If num must be modified:

type data struct { num int key *string items map[string]bool
} func (d *data) vmethod() { d.num = 8
} func (d *data) run() { d.vmethod() fmt.Printf("%+v", d) // Output: &{num:8 key:0xc00010a040 items:map[1:true]}
}

4. Possibly undesired value being used in goroutine

Range variables in a loop are reused at each iteration; therefore, a goroutine created in a loop will point to the range variable from the upper scope. This way, the goroutine could use the variable with an undesired value.

In the example below, the value of index and value used in the goroutine are from the outer scope. Because the goroutines run asynchronously, the value of index and value could be (and usually are) different from the intended value.

mySlice := []string{"A", "B", "C"}
for index, value := range mySlice { go func() { fmt.Printf("Index: %d\n", index) fmt.Printf("Value: %s\n", value) }()
}

To overcome this problem, a local scope must be created, like in the example below.

mySlice := []string{"A", "B", "C"}
for index, value := range mySlice { index := index value := value go func() { fmt.Printf("Index: %d\n", index) fmt.Printf("Value: %s\n", value) }()
}

Another way to handle this could be by passing the values as args to the goroutines.

mySlice := []string{"A", "B", "C"}
for index, value := range mySlice { go func(index int, value string) { fmt.Printf("Index: %d\n", index) fmt.Printf("Value: %s\n", value) }(index, value)
}

5. Deferring `Close` before checking for a possible error

It’s a common pattern amongst Go developers, to defer the Close() method for a value that implements the io.Closer interface. For example, when opening a file:

f, err := os.Open("/tmp/file.md")
if err != nil { return err
}
defer f.Close()

But this pattern is harmful for writable files because deferring a function call ignores its return value, and the Close() method can return errors. For instance, if you wrote data to the file, it might have been cached in memory and not flushed to disk by the time you called Close. This error should be explicitly handled.

While you could go ahead without using defer at all, you would need to remember to close the file everytime their job is done. A better way would be to defer a wrapper function, like in the example below.

f, err := os.Open("/tmp/file.md")
if err != nil { return err
} defer func() { closeErr := f.Close() if closeErr != nil { if err == nil { err = closeErr } else { log.Println("Error occured while closing the file :", closeErr) } }
}()
return err

Recommended reading: Do not defer Close() on writable files

go build!

Leveraging static code analysis in a Ruby CI pipeline

Saif Sadiq — Tue, 02 Mar 2021 17:18:06 +0000

Continuous integration, or CI, refers to the culture and the technologies that enable continuously merging features and bug fixes into the main branch of the codebase. Code changes are incorporated immediately after testing, rather than being bunched with other updates in a waterfall release process.

Similarly, continuous delivery, or CD, refers to automatically deploying the changed code to the target environment, such as pre-production branches to staging and master to production. CD picks up where CI left off, and as such, they often go hand in hand.

Static code analysis typically falls under the CI aspect of a CI/CD pipeline. Taking the example of a small Ruby project, we’ll be setting up a CI workflow to analyze code quality using static analysis in the following areas:

Consistency, with the widely adopted Ruby style guide.
Layout, such as unjust spacing or misaligned indentation.
Linting, such as inadequate permissions or redundant operations.
Security analysis, such as the use of unsafe methods.

Prerequisites

Creating a sandbox

Let’s make a fresh new directory for our adventure today. Initialize a Git repository in the folder and check it into GitHub as we’ll be using GitHub Workflows as our CI tool (more on this later).

$ mkdir proj
$ cd proj/
$ touch .gitignore

Setting up Ruby and Bundler

You probably already have Ruby installed on your computer. But I find it best not to use pre-installed Ruby for a couple of reasons. Reason the first, it’s generally much older than the latest stable version, and you don’t want to miss out on Ruby’s newest features, do you? Reason the second, it’s relatively easy to break your system by installing, removing, or updating a critical package.

Don’t fret; there’s a solution — RVM. I won’t get into details of RVM here, but using it, you can install and manage several versions of Ruby on a system, keeping the system Ruby pristine.

$ rvm install 3.0.0
$ rvm use 3.0.0

Next, we set up Bundler, a fantastic package manager for Ruby. We need it to keep track of our projects dependencies. It’s extremely straightforward to install.

$ gem install bundler
$ bundle init

To ensure that our project gems remain localized to our project, we can set up Bundler to install Gems at a given path. Create a directory .bundle/ and a config file within the directory with the following content.

With this configuration, Bundler will install all gems inside a .gems/ folder inside the current project folder proj/. Add both directories .bundle/ and .gems/ to your .gitignore file so that they are not checked into VCS.

Getting familiar with Rubocop

For analyzing the code quality in all the areas we mentioned above, we will be using Rubocop, one of the finest linters available for Ruby. Rubocop comes with an extensive collection of rules, called ‘cops’, organized in groups, called ‘departments’, based on their functionality.

To install, add the line to your Gemfile and run bundle install.

# frozen_string_literal: true source 'https://rubygems.org' git_source(:github) { |repo_name| "https://github.com/#{repo_name}" } + gem 'rubocop', '~> 1.9', require: false

To list all the offences in any given file or directory, just pass the names as arguments to rubocop.

$ rubocop <file/dir_name>

Rubocop is also capable of autocorrecting most of the errors it reports, which is incredibly helpful. To enable autocorrection, pass the -a flag. Passing -A uses a more aggressive auto-correct mode, which is not advisable unless you are sure of what you are doing.

$ rubocop -a <file/dir_name> # safe autocorrect, recommended
$ rubocop -A <file/dir_name> # unsafe autocorrect, not recommended

You will need to prepend bundle exec to these commands if Rubocop is not globally installed.

The code

Now we get to the fun part, scripting in Ruby. Take this script, for example. It takes a file name as an argument and prints said file’s content to STDOUT, very similar to the cat command (hence the name).

# cat.rb
filename = ARGV[0] file = open(filename)
list = file.read
file.close list.each_line.with_index{|line| puts line
}

It is formatted poorly, violates many rules from the style guide, and even has a couple of gaping security flaws. We’ll fix those pretty soon but first, let’s do a preliminary scan with Rubocop and observe the output.

$ bundle exec rubocop cat.rb
Inspecting 1 file
W Offenses: cat.rb:1:1: C: [Correctable] Style/FrozenStringLiteralComment: Missing frozen string literal comment.
# cat.rb
^
cat.rb:4:8: C: Security/Open: The use of Kernel#open is a serious security risk.
file = open(filename) ^^^^
cat.rb:8:16: W: [Correctable] Lint/RedundantWithIndex: Remove redundant with_index.
list.each_line.with_index{|line| ^^^^^^^^^^
cat.rb:8:26: C: [Correctable] Layout/SpaceBeforeBlockBraces: Space missing to the left of {.
list.each_line.with_index{|line| ^
cat.rb:8:26: C: [Correctable] Layout/SpaceInsideBlockBraces: Space between { and | missing.
list.each_line.with_index{|line| ^^
cat.rb:8:26: C: [Correctable] Style/BlockDelimiters: Avoid using {...} for multi-line blocks.
list.each_line.with_index{|line| ^
cat.rb:10:2: C: [Correctable] Layout/TrailingEmptyLines: Final newline missing.
} 1 file inspected, 7 offenses detected, 6 offenses auto-correctable

Rubocop found 7 offenses, of which 6 it can correct automatically, labeled as [Correctable] in the output above.

Pipeline

Picking the infrastructure

Choices abound when it comes to picking a CI/CD infrastructure provider. From Travis CI, a darling of open-source developers, to Jenkins, the tool of choice for enterprise teams who’d rather self-host their customized solution, dev-ops engineers are spoilt for choice.

But the simplest of these in my experience has been GitHub workflows, a GitHub-native solution allowing you to set up entire chains of jobs, described as YAML files, that can be initiated based on specific triggers. We can use them throughout the CI/CD pipeline, from running checks on PRs before merge to deploying the code after. There are hundreds of pre-built actions (many officially maintained) that take the effort out of setting up end-to-end pipelines.

Naturally, we’ll be using GitHub workflows as our CI pipeline infrastructure. The end goal is to have linting as a check on our PRs and commits. Only PRs that pass the checks would be mergeable.

Adding lint workflow

Let’s see what the workflow file would look like in our case. Create a new directory .github/, create another directory within this one named workflows/, and in this directory, create a file named lint.yml.

# .github/workflows/lint.yml
name: Lint

on:
 push:
 branches:
 - master

jobs:
 lint:
 name: Lint
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v2
 - uses: ruby/setup-ruby@v1
 with:
 ruby-version: 3.0
 bundler-cache: true # runs `bundle install`
 - run: bundle exec rubocop .

The lint workflow consists of a single job. The job is fired on every push event to the master branch and performs three steps:

actions/checkout: checks out the code repository
ruby/setup-ruby:
1. sets up Ruby version 3.0 and the latest compatible version of Bundler
2. uses Bundler to install all packages in the Gemfile
run: runs Rubocop on the entire current working directory

Once the job completes, we get our outcome. In our case, it’s a big red cross. The workflow execution fails because Rubocop found issues in the code. The logs reveal the same message we had seen earlier, and lists offences identified by Rubocop.

😢 We’ll get there, eventually.

Fixing problems

We want our check to pass. Nobody likes failing checks. Coming back to our local setup, let’s use Rubocop’s autofix feature to quickly resolve these issues. First, we should let Rubocop take care of the automatic stuff using the -a flag.

$ bundle exec rubocop -a cat.rb
Inspecting 1 file
W Offenses: cat.rb:1:1: C: [Correctable] Style/FrozenStringLiteralComment: Missing frozen string literal comment.
# cat.rb
^
cat.rb:4:8: C: Security/Open: The use of Kernel#open is a serious security risk.
file = open(filename) ^^^^
cat.rb:8:15: C: [Corrected] Layout/ExtraSpacing: Unnecessary spacing detected.
list.each_line do |line| ^
cat.rb:8:16: W: [Corrected] Lint/RedundantWithIndex: Remove redundant with_index.
list.each_line.with_index{|line| ^^^^^^^^^^
cat.rb:8:26: C: [Corrected] Layout/SpaceBeforeBlockBraces: Space missing to the left of {.
list.each_line.with_index{|line| ^
cat.rb:8:26: C: [Corrected] Layout/SpaceInsideBlockBraces: Space between { and | missing.
list.each_line.with_index{|line| ^^
cat.rb:8:26: C: [Corrected] Style/BlockDelimiters: Avoid using {...} for multi-line blocks.
list.each_line.with_index{|line| ^
cat.rb:10:2: C: [Corrected] Layout/TrailingEmptyLines: Final newline missing.
} 1 file inspected, 8 offenses detected, 6 offenses corrected, 1 more offense can be corrected with `rubocop -A`

Rubocop solved most of the issues reported, including one issue introduced during the autofix process itself! With 6 of the 7 problems are already fixed, we’ve managed to shave off ~70% of our work with zero effort input.

What’s left is one unsafe autofix and one security vulnerability that Rubocop cannot fix automatically. We can take care of those:

The frozen string literal comment is missing. That’s a reasonable thing to add to the file, so we’ll let Rubocop add it using the stronger autofix flag -A.

$ bundle exec rubocop -A cat.rb
Inspecting 1 file
C Offenses: cat.rb:1:1: C: [Corrected] Style/FrozenStringLiteralComment: Missing frozen string literal comment.
# cat.rb
^
cat.rb:2:1: C: [Corrected] Layout/EmptyLineAfterMagicComment: Add an empty line after magic comments.
# cat.rb
^
cat.rb:6:8: C: Security/Open: The use of Kernel#open is a serious security risk.
file = open(filename) ^^^^ 1 file inspected, 3 offenses detected, 2 offenses corrected

- file = open(filename)
+ file = File.open(filename)

Commit and push. We’re green now! At this point, you should pat yourself on the back for a job well done.

🥳 Yay!

Staying clean

Now that you’re at peak code quality, we need to ensure it stays that way. This means that we need to ensure that no PR negatively affects our codebase quality. To run the check on every incoming PR, add the pull_request event to our lint workflow.

on: on: push: branches: - master
+ pull_request:
+ branches:
+ - master

Now, to test that our check is working as expected, we need to make a PR with some code that Rubocop would flag. Let’s refactor the lines in our script, that are concerned with reading the file, to use a block.

# cat.rb # frozen_string_literal: true filename = ARGV[0] - file = File.open(filename)
- list = file.read
- file.close
+ File.open(filename) do |file|
+ list = file.read
+ end

list.each_line do |line|
  puts line
end

Check out a new branch from master. Commit and push to this branch and open a PR. You’ll see that the checks fail, and thus the PR cannot be merged unless overridden by an administrator.

🚧 Our check is working just fine!

🧠 Brain-teaser: Can you identify why the updated code, using a block, is being flagged by Rubocop?

🤷‍♂️ Hint: If you want a hint, here’s the Rubocop output for the PR:

$ bundle exec rubocop cat.rb
Inspecting 1 file
W

Offenses:

cat.rb:7:3: W: Lint/UselessAssignment: Useless assignment to variable - list.
  list = file.read
  ^^^^

1 file inspected, 1 offense detected

🧑‍💻 Answer: Defining list inside the block means that it is not accessible outside the block. This makes the assignment useless and will lead to a bug in the subsequent use of the variable.

💡 Lesson: Though indirectly, code analysis can sometimes also help identify potential bugs!

DeepSource

While we invested considerable time and effort, we now have checks and actions set up to monitor code quality in our repo. But what if we didn’t have time to spare or didn’t want to spend the effort? We’re busy developers, after all!

Consider using DeepSource. It continuously scans the code on every commit, and on every pull request, through various static code analyzers (including linters and security analyzers), and can automatically fix some of them. DeepSource also has its custom-built analyzers for most languages that are constantly improved and kept up-to-date.

It’s incredibly easy to set up! You need only add a .deepsource.toml file in your repository root, and DeepSource will pick it up. It takes much less effort and the end result is way more polished that setting up several workflows in GitHub.

version = 1

[[analyzers]]
name = "ruby"
enabled = true

[[transformers]]
name = "rubocop"
enabled = true

Automate the tedium away

CI/CD pipelines are quintessential to the agile development workflow. The ability to add features, squash bugs, and get the changes in production instantly can make a very significant difference. Startups live or die based on how often they iterate.

Integrating static analysis into the CI pipeline ensures that only the cleanest and most compliant code makes its way into production. For something that takes very little time to set up, consumes a minuscule amount of resources, and does not significantly affect test/build timings, static analysis can add a lot of confidence to your build process.

Confident iterations await. Till next time!

Automate code formatting in Python

Saif Sadiq — Tue, 16 Feb 2021 08:06:53 +0000

Right off the bat, let’s clarify an important distinction. Writing code that works and writing good code are two very different things. The former is a skill while the latter is an art form, and this difference distinguishes great programmers from the crowd.

When we talk of good code, the word ‘good’ is vague by design. That’s because there are no rules set in stone about what makes code good or bad. All we have are some abstract guidelines such as readability:

Programs are meant to be read by humans and only incidentally for computers to execute.

– Abelson & Sussman

Those are two MIT professors with pretty solid credentials. Identifying the quality of code is an intuition that is honed over time, through practice and experience. Code reviews go a long way towards this goal.

Code review is the process where developers more experienced than yourself read through your code and suggest improvements that could make it better. These suggestions can improve performance, incorporate new language features, patch security oversights, or correct code style.

... when it comes to code review.

But manual code reviews are expensive. The time it takes someone to read your code is time they did not spend building awesome stuff. They are also error-prone and by no means comprehensive. There are human limits to knowledge and memory.

Enter automation. Automated code reviews are faster, less error-prone, and more in-depth than their manual counterparts.

Let’s dive deep into the process with a sample project containing a single Python file. We’ll riddle the file with issues and then set up a workflow that automatically finds and fixes these problems.

Ingredients

A. Codebase with PEP-8 violations

Before we automate code review, let’s first write some code to review. Here is a sample program that lists primes up to a given number. It might hurt to look at, which is good as it means your code-olfactory senses are working.

# list_primes.py
def is_prime (number): for i in range(2, number): if number%i==0: return False return True def list_primes(upper): for number in range(2, upper): if is_prime(number): print(F"{number} is prime") list_primes(10)

There are a lot of problems with this script. Don’t get me wrong, it works, but it’s not good.

Extraneous space before function parenthesis
2-space indentation
No spaces around operators
Single line around functions
Uppercase F in f-strings

B. Black code formatter

Black is a popular code formatter for Python. It is capable of automatically reformatting your Python files, fixing all code style violations. What’s neat is that it is pretty opinionated and can’t be configured much, making it ideal for automation.

So let’s install Black, while also taking the opportunity to set up some first-class dependency management with a tool I personally love, Pipenv. Running the following command creates two files, Pipfile and Pipfile.lock, in the root of the repo and installs Black as a dev dependency.

$ pipenv install --pre --dev black

Running Black without any args formats all files in the repo directly. Apart from reformatting your files, it has two less dangerous modes.

--check: In this mode, Black purely checks if there are any code style violations. The return code is 0 if there are no violations and non-zero if there are any.

$ pipenv run black --check list_primes.py
would reformat /Users/dhruvkb/Documents/scratch/automata/list_primes.py
Oh no! 💥 💔 💥
1 file would be reformatted.

--diff: In this mode, Black shows the changes it will make without actually making them. This mode is helpful if you want to inspect the changes before they are actually made.

$ pipenv run black --diff list_primes.py
--- list_primes.py  2020-02-02 00:00:00.000000 +0000
+++ list_primes.py  2020-02-02 00:00:00.000000 +0000
@@ -1,17 +1,19 @@
 # list_primes.py
-def is_prime (number):
+def is_prime(number):
- for i in range(2, number):
+ for i in range(2, number):
- if number%i==0:
+ if number % i == 0:
- return True
+ return True

- return False
+ return False
+
 def list_primes(upper): for number in (2, 10): if is_prime(number):
- print(F"{number} is prime")
+ print(f"{number} is prime")
+

 list_primes(15)

Recipe

Code review can be split in two parts: the interesting part where you solve big picture issues and the mundane parts where you identify non-idiomatic snippets and code style violations. Let’s automate the boring parts of the code review.

1. Set up Git hooks

We just saw how incredible Black is. Wouldn’t it be awesome if Black ran automatically every time you were to commit your code? It’s possible, with Git hooks. Git hooks are programs that run on your codebase when you execute certain Git commands. The ‘pre-commit’ hook is of particular interest to us because we’d like the lint check to take place before the commit is created, and prevent the commit from being created if it fails.

Autohooks is a Python package for managing these hooks via Python. It has a plugin system that enables integration with tools like Black. Let’s install both Autohooks and the Black-integration plugin.

$ pipenv install --dev autohooks autohooks-plugin-black

Make a pyproject.toml file in the root of your repo with the following content.

[tool.autohooks]
mode = "pipenv"
pre-commit = ["autohooks.plugins.black"]

[tool.autohooks.plugins.black]
arguments = ["--check"]

Activate the hooks and run the check function to see if everything works fine.

$ pipenv run autohooks activate
✓ autohooks pre-commit hook installed at /Users/hal/Documents/scratch/.git/hooks/pre-commit using pipenv mode.

$ pipenv run autohooks check
✓ autohooks pre-commit hook is active.
✓ autohooks pre-commit hook is up-to-date.
ℹ Using autohooks mode "pipenv".
✓ Plugin "autohooks.plugins.black" active and loadable.

Try git commit-ing the poorly written source code. Ha, gotcha! Here’s how things will go down:

The pre-commit hook will be initiated.
The top-level hooks by Autohooks will be invoked.
Autohooks will then execute Black with the --check argument.
Black will return a non-zero code because the file contains errors.
Git will halt the commit operation.

$ git add . && git commit -m "Add the source code to VCS"
ℹ autohooks => pre-commit
ℹ Running autohooks.plugins.black
would reformat /Users/dhruvkb/Documents/scratch/automata/list_primes.py
Oh no! 💥 💔 💥
1 file would be reformatted.
×

💡 Pro-tip: You can bypass the hook with the --no-verify flag on git commit. It’s not recommended but we’re not the police, so do what you want.

💡 Pro-tip: You can remove the --check argument and then every time you commit, Black will reformat your files for you.

2. Lint check using GitHub Actions

The main drawback of Git hooks is that they are local. In a project with multiple contributors, there might be people who might forget to activate the hook or actively try to bypass them. In such cases, the solution is to run the lint check on the remote repo itself. GitHub Actions provides an extremely versatile solution for running the lint.

Create the file lint.yml inside the .github/workflows directory of the repo.

# .github/workflows/lint.yml
name: Lint

on: [push, pull_request]

jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v2
 - uses: actions/setup-python@v2
 - uses: psf/black@stable

This workflow checks out the repository, sets up Python, installs Black and then lints the files. By default, this action runs Black with the --check and --diff arguments. Once you set up linting, all future commits and PRs will pass through Black.

Our list_primes.py file will fail the test. The logs will show both the failing files as well as the diffs for those files (because of the -diff argument). That’ll come in pretty handy when you’re fixing the violations.

3. Lint fixes using GitHub Workflows

That brings us to the one aspect we still haven’t addressed yet. Black is capable of reformatting files, but so far, we have only used it to detect issues and present diffs. We’ve not tapped into Black’s full potential yet.

How about we turn the automation up to 11 and update our GitHub workflow to automatically fix code style violations?

# .github/workflows/lint.yml
name: Lint

on: - push
- workflow_dispatch

jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v2
 - uses: actions/setup-python@v2
 - name: Install Python dependencies
 run: |
 pip install pipenv
 pipenv install --deploy --dev --system
 - uses: wearerequired/lint-action@v1
 with:
 github_token: ${{ secrets.GITHUB_TOKEN }}
 black: true
 auto_fix: true

This workflow uses the same two steps as the previous one, that is checking out the repo and setting up Python. Then we install Pipenv and use that to install Black on the system. The lint-action action runs Black and then commits the changed files. This creates a new commit with the same changes that Black had shown in the diff!

💡 Pro-tip: You can customize the author’s name and email and also the message of the commit. Just add the following to the with key of the action. It’s an opportunity to be creative!

commit_message: 'Opening the pod-bay doors'
git_name: 'HAL-9000'
git_email: 'hal@hal.hal'

Now that you can be assured that code pushed to the repo is free from style guide deviations, this frees up code reviewers to take a bigger picture look at the code and leave the minutiae to HAL.

End-to-end automation with DeepSource

Phew! That was a lot of work, wasn’t it? But guess what, we only looked at style guide violations for now. Adding more features like looking for security gaps, finding possible bugs, and making complex refactors would make this a very long exercise. But it does not have to be.

You could also consider automating this entire audit, review and refactor process with DeepSource that can scan your code on every commit, and for every pull request, through several tools (including linters and security analyzers) and can automatically fix many issues. DeepSource also has its custom-built analyzers for most languages that are constantly improved and kept up-to-date.

It’s incredibly easy to set up! You need only add a .deepsource.toml file in your repository root, and DeepSource will pick it up. Much less effort than what we just went through.

version = 1

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  runtime_version = "3.x.x"
  max_line_length = 80

[[transformers]]
name = "black"
enabled = true

Finis coronat opus

Code reviews are a very important learning tool for new developers. It’s a way to transfer knowledge, experience, and convention from a senior developer to a junior, a way to understand how even the code that was deemed as final can be made better, cleaner, and more efficient.

I’d venture so far as to say that code reviews are one of the best learning tools for developers, and they are wasted on mundane things like code style. Introduce a little automation and make every code review count.

They know enough who know how to learn.

When done well, a code review can be a truly educational experience. Automation cannot replace that. What automation can do is take the mundane out of the process.

Here’s to better code reviews!

Common Python security pitfalls, and how to avoid them

Saif Sadiq — Wed, 10 Feb 2021 17:43:05 +0000

Python is undoubtedly a popular language. It consistently ranks among the most popular and most loved languages year after year. That’s not hard to explain, considering how fluent and expressive it is. Its pseudocode-like syntax makes it extremely easy for beginners to pick it up as their first language, while its vast library of packages (including the likes of giants like Django and TensorFlow) ensure that it scales up for any task required of it.

Being such a widely-used language makes Python a very attractive target for malicious hackers. Let’s see a few simple ways to secure your Python apps and keep the black-hats at bay.

Problems and solutions

Python places a lot of importance on zen, or developer happiness. The clearest evidence of that lies in the fact that the guiding principles of Python are summarized in a poem. Try import this in a Python shell to read it. Here are some security concerns that might disturb your zen, along with solutions to restore it to a state of calm.

Unsafe deserialization

OWASP Top Ten, a basic checklist for web security, mentions unsafe deserialization as one of the ten most common security flaws. While it’s common knowledge that executing anything coming from the user is a terrible idea, serializing and deserializing user input does not seem equally serious. After all, no code is being run, right? Wrong,

PyYAML is the de-facto standard for YAML serialization and deserialization in Python. The library supports serializing custom data types to YAML and deserializing them back to Python objects. See this serialization code here and the YAML produced by it.

# serialize.py
import yaml class Person: def __init__ (self, name, age): self.name = name self.age = age def __str__ (self): return f'<Person: {self.name} - {self.age}>' def __repr__ (self): return str(self) person = Person('Dhruv', 24)
with open('person.yml', 'w') as output_file: yaml.dump(person, output_file)

!!python/object: __main__.Person
age: 24
name: Dhruv

Deserializing this YAML gives back the original data type.

# deserialize.py
import yaml # class Person needs to be present in the scope
with open('person.yml', 'r') as input_file: person = yaml.load(input_file, Loader = yaml.Loader) print(person)

$ python deserialize.py ↵
<Person: Dhruv - 24>

As you can see, the line !!python/object: __main__.Person in the YAML describes how to re-instantiate objects from their text representations. But this opens up a slew of attack vectors, that can escalate to RCE when this instantiation can execute code.

Solution

The solution, as trivial as it may seem, is to use safe-loading by swapping out the loader yaml.Loader in favor of the yaml.SafeLoader loader. This loader is safer because it completely blocks loading of custom classes.

# deserialize.py
import yaml # class Person needs to be present in the scope
with open('person.yml', 'r') as input_file: person = yaml.load(input_file, Loader = yaml.SafeLoader) print(person)

$ python deserialize.py ↵
ConstructorError: could not determine a constructor for the tag 'tag:yaml.org,2002:python/object: __main__.Person'
  in "person.yml", line 1, column 1

Standard types like hashes and arrays can still be serialized to and deserialized from YAML documents just like before. Most people, probably including you, won’t even realize the difference.

age: 24
name: Dhruv

$ python deserialize.py ↵
{'age': 24, 'name': 'Dhruv'}

Dynamic execution

Python has a pair of very dangerous functions: exec and eval. Both are very similar in terms of what they do: process the strings passed to them as Python code. exec expects the string to be a statement, which it will execute and not return a value. eval expects the string to be an expression and will return the computed value of the expression.

Here is an example of what both these functions in action.

eval('2 + 5') # returns 7
exec('print("Hello")') # prints "Hello", no return

You could in theory, pass a statement to eval and get a similar effect as exec, because in Python returning None is virtually the same as not returning anything at all.

eval('print("Hello")') # prints "Hello", returns None

The danger of these functions lies in the ability of these functions to execute virtually any code in the same Python process. Passing any input to the function that you cannot be 100% certain about, is akin to handing over your server keys to malicious hackers on a plate. This is the very definition of RCE.

Solution

There are ways to mitigate the access that eval has. You can restrict access to globals and locals by passing dictionaries as the second and third arguments to eval respectively. Remember that locals take priority over globals in case of conflict.

x = 3
eval('x + 5') # returns 8
eval('x + 5', { 'x': 2 }) # returns 7
eval('x + 5', { 'x': 2 }, { 'x': 1 }) # returns 6

That makes the code safer yes. At least it somewhat prevents the data in the variables from being leaked.

But it still doesn’t prevent the string from accessing any built-ins like pow, or more dangerously, __import__. To counter that, you need to override __builtins__.

eval(" __import__ ('math').sqrt(5)", {}, {}) # returns 2.2360679774997898
eval( " __import__ ('math').sqrt(5)", { " __builtins__": None }, {} # restricts access to built-ins
) # error

Safe to expose now? Not quite. Because regardless of how secure you make eval, it’s job is to evaluate an expression and nothing can stop the expression from taking too long and freezing the server for a long time.

eval("2 ** 2147483647", { " __builtins__": None }, {}) # goodbye!

As we Python developers like to say, “eval is evil.”

Dependency management

Python’s popularity draws the attention of white-hat security researchers just as much as it does that of hackers with malicious intent. As a result, new security vulnerabilities that are constantly discovered, disclosed, and patched. To keep the malicious hackers at bay, your software needs to keep all its dependencies up to date.

A common technique for pinning packages in Python is the ubiquitous requirements.txt file, a simple file that lists all the dependencies and exact versions needed by your project.

Let’s say you install Django. As of writing, Django depends on three more packages. If you freeze your dependencies, you end up with the following requirements. Note that only one of these dependencies was installed by you, the other 3 are sub-dependencies.

$ pip freeze ↵
asgiref==3.3.1
Django==3.1.5
pytz==2020.5
sqlparse==0.4.1

pip freeze does not place dependencies in levels and that’s a problem. For smaller projects with a few dependencies that you can keep a track of mentally, this is not a big deal but as your projects grow, so will your top level dependencies. Conflicts arise when sub-dependencies overlap. Updating individual dependencies is a mess too, because the graph relationship of these dependencies is not clear from the plain text file.

Solution

Pipenv and Poetry are two tools that help you manage dependencies better. I prefer Pipenv but Poetry is equally good. Both package managers build on top of pip. Fun fact: DeepSource is compatible with both Pipenv and Poetry as package managers.

Pipenv, for example, tracks your top-level dependencies in a Pipfile and then does the hard work of locking down dependencies in a lockfile name Pipfile.lock, similar to how npm manages Node.js packages. Here’s an example Pipfile.

[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true

[dev-packages]

[packages]
django = "*"

[requires]
python_version = "3.9"

With this, you can get a clear picture of the top-level dependencies of your app. Updating dependencies is also much easier because you just need to update the top level packages and the locking algorithm will figure out the most compatible and up-to-date versions of all the sub-dependencies.

Here is the same example with Django. Notice how Pipenv can identify your top-level dependencies and its dependencies and so on.

$ pipenv graph ↵
Django==3.1.5
  - asgiref [required: >=3.2.10,<4, installed: 3.3.1]
  - pytz [required: Any, installed: 2020.5]
  - sqlparse [required: >=0.2.2, installed: 0.4.1]

If your code is hosted on GitHub, make sure you turn on and configure Dependabot as well. It’s a nifty little bot that alerts you if any of your dependencies has gone out of date or if a vulnerability has been identified in the pinned version of a dependency. Dependabot will also make PRs to your repo, automatically updating your packages. Very handy indeed!

Runtime assertions

Python has a special assert keyword for guarding against unexpected situations. The purpose of assert is simple, verify a condition and raise an error if the condition is not fulfilled. In essence, assert evaluates the given expression and

if it evaluates to a truthy value, moves along
if it evaluates to a falsey value, raises an AssertionError with the given message

Consider this example.

def do_something_dangerous(user, command): assert user.has_permissions(command), f'{user} is not authorized' user.execute(command)

This is a very simple example where we check if the user has the permissions to perform an action and subsequently perform the given action. In this case, if user.has_permissions() returns False, our assertion would cause an AssertionError and the execution would be halted. Seems pretty safe, right?

No. Assertions are tools for developers during development and debugging phases. Asserts should not be used to guard critical functionality. The Python constant, __debug__ is set to False during compilation, which removes assert statements from the compiled code to optimise the code for performance. Removing assert statements from the compiled code leaves the function unguarded.

Another reason to avoid asserts is that assertion errors are not helpful to debuggers as they provide no information other than the fact that an assertion did not hold up. Defining apt exception classes and then raising their instances is a much more solid solution.

Solution

For an alternative approach, go back to the basics. Here’s the same program, this time using if/else and a raising a PermissionError (you’ll need to define it somewhere) when the required assertion is unfulfilled.

def do_something_dangerous(user, command): if user.has_permissions(command): # [safer as it will not be removed by compiler user.execute(command) else: raise PermissionError(f'{user} is not authorized') # suitable error class

This code uses straightforward Python constructs, works the same with __debug__ set to True or False and raises clear exceptions that can be handled with much more clarity.

Achieving Zen

The key takeaway from all of these examples is to never trust your users. Input provided by the users should not be serialized-deserialized, evaluated, executed or rendered. To be safe, you must be careful of what you write and thoroughly audit the code after its been written.

Do you know what’s better than scanning for vulnerabilities in code after it’s been written? Getting vulnerabilities highlighted as soon as you write code with them.

Bandit

Static Code Analysis tools such as linters and vulnerability scanners can help you find a lot of issues before they get exploited in the wild. An excellent tool for finding security vulnerabilities in Python is Bandit. Bandit goes through each file, generates an abstract syntax tree (AST) for it and then runs a whole slew of tests on this AST. Bandit can detect a whole bunch of vulnerabilities out-of-the-box and can also be extended for specific scenarios and compatibility with frameworks via plugins. As a matter of fact, Bandit is capable of detecting all of the aforementioned security shortcomings.

If you’re a Python developer, I cannot recommend Bandit enough. I could write a whole article extolling its virtues. I might even do that.

DeepSource

You should also consider automating this entire audit and review process using code review automation tools like DeepSource that scans your code, on every commit and for every PR, through it’s linters and security analyzers and can automatically fix a multitude of issues. DeepSource also has its own custom-built analyzers for most languages that are constantly improved and kept up-to-date. And it’s incredibly easy to set up!

version = 1

[[analyzers]]
name = "python"
enabled = true

  [analyzers.meta]
  runtime_version = "3.x.x"
  max_line_length = 80

Who knew it could be so simple?

Experience the zen of Python, and be careful not to let black-hats disturb your peace!

Ruby best practices beginners should know

Saif Sadiq — Mon, 18 Jan 2021 06:36:08 +0000

Python’s dominance is never really questioned when it comes to the best for programming novices because it checks almost every box that defines a simple language. It’s remarkably easy to pick up and can rise to any challenge. But what about Ruby?

Although it does not get enough credit for being one, Ruby is an awesome language for beginners. It provides powerful constructs (like blocks) and versatile concepts (like message passing à la Smalltalk) but retains Python’s fluid and elegant English-like syntax. In fact, in many cases, one might argue that the unique design choices that went into the Ruby syntax beat even Python in terms of readability and expressiveness. If you’re getting into programming, it’s very easy to recommend that you go with Ruby.

This article aims to establish some practices that are generally accepted by the Ruby programming community. Before we dive right into how you, as a beginner, can channel Ruby’s power, let me mention two Japanese phrases that you should hold in memory: “okonomi” and_“omakase”_. I promise this is relevant, and you’ll see why in a bit.

“Okonomi”

Ruby has always been driven by the principle to “optimize for programmer happiness” and, as a result, always offers several different ways to do the same thing, unlike Python, which has valued the philosophy of having “one and preferably only one way to do something”. As a result, many people who come to Ruby from another language find themselves baffled at the sheer number of choices the language offers for accomplishing any given task.

This is what the Japanese call “okonomi”, a phrase that typically applies to sushi, which translates to “I’ll choose what to order”.

Statements are expressions

In Ruby, there are no statements. Every line and every command is an expression that evaluates to something. Even function definitions return something, the symbolized function name.

So while you cannot hold functions in variables (something Python and JavaScript allow), you can hold their identifiers as symbols and invoke them with send (more on that in a bit).

name = 'DeepSource' # returns the string 'DeepSource' itself...
b = name = 'DeepSource' # ...so this is also valid puts name # displays "DeepSource" and returns nil name.split('').select do |char| char.downcase == char # block returns true or false
end # returns ["e", "e", "p", "o", "u", "r", "c", "e"] def prime? num # ...
end # returns :prime?

How do you make the most of this? This particular design decision leads to a few notable features, the most recognizable of which is that both the return and next keywords are, for the most part, redundant, and the recommendation is not to use them unless you want to terminate the function or block early.

def prime? num if num >= 2 f = (2...num).select do |i| ~~next~~ num % i == 0 end ~~return~~ f.size == 0 else ~~return~~ false end
end

Bye bye brackets

In Ruby function, parentheses are, with certain caveats, optional as well. This makes Ruby ideal for defining domain-specific languages or DSLs. A domain-specific language is a language built on top of another that defines abstractions for a specific specialized purpose.

For examples of DSLs, you need not look further than Rails or RSpec but for the sake of simplicity, consider Sinatra, a straightforward web server built in Ruby. This is how a simple service would look built with Sinatra.

require 'sinatra' get '/' do 'Hello, World!'
end

What’s not immediately apparent from this example is that get here, which looks very much like a language keyword, is actually a function! The get function here takes two arguments, a string path and a block that contains the code to be executed when the path matches. The return value of the block will be the HTTP response for the request matching the method and path.

How do you make the most of this? By embracing this freedom, you can define your own abstractions for your use cases! Ruby actively encourages developers to define their own little DSLs for day-to-day abstractions and write clean code by using them. The best part is that code then reads like pseudocode which is always a good thing.

While parentheses are optional, the convention is to generally omit the parentheses only for zero or one arguments, while retaining them when there are more than one, for the sake of clarity.

require 'date' def log message timestamp = DateTime.now.iso8601 puts "[#{timestamp}] #{message}" end log "Hello World!"
# [2020-12-30T21:18:30+05:30] Hello World!

Method names?!

Ruby enables method names to have all sorts of punctuation such as =,?, !. Each of these punctuation has its purpose, by convention, and indicates the particular function’s nature.

| Punctuation | Purpose | Example |
|-------------|-----------------------------------------------|-----------|
| `?` | Returns a Boolean value, `true` or `false` | .nil? |
| `!` | Modifies values in place or raises exceptions | .reverse! |

Many Ruby functions come in two variants, regular and “bang”. To understand the difference, consider this example with two variants of the reverse method on strings.

str = 'DeepSource' str.reverse # "ecruoSpeeD"
str # "DeepSource" str.reverse! # "ecruoSpeeD"
str # "ecruoSpeeD"

In Ruby, functions with the exclamation mark in the name modify the object they are called on. In Rails, the exclamation mark indicates that the function will raise an exception if it cannot accomplish said task instead of failing silently like its non-bang counterpart.

How do you make the most of this? You should imbibe the same convention in your code so that users of the code can easily get an idea of the function’s nature.

Symbols over strings

The concept of symbols is something unique to Ruby. Symbols are just strings that are interned in memory and are not allocated new memory every time they are defined.

'text'.object_id # 200
'text'.object_id # 220 :text.object_id # 2028508
:text.object_id # 2028508

Symbols are used in tons of places across Ruby, notably as keys for hashes and constants defining identifiers and functions.

You can symbolize a string in two ways, prefixing the colon: before the string (quotes are required unless the string is a valid identifier) or invoking to_sym method on it.’

:identifier # :identifier
:'not an identifier' # :"not an identifier"
'not_an_identifier'.to_sym # :"not an identifier"

How do I make the most of this? The standard of defining hashes in Ruby is by using the “rocket operator” =>. But using hashes presents a concise, cleaner, and more JavaScript-esque way to define the same.

person_one = { 'name' => 'Alice', 'age' => 1 }
person_one['name'] # 'Alice' person_two = { :name => 'Bob', :age => 2 } # Replace strings with symbols
person_two[:name] # 'Bob' person_two = { name: 'Carol', age: 3 } # Use new style
person_two[:name] # 'Carol'

The second notation is easier to read, performs better for larger data sizes, and is widely recommended now as the preferred way to define hashes. Symbols are also used for passing messages to objects usingsend !).

Talk over messages

Ruby inherits the concept of message passing from Smalltalk and goes all-in with this idea. Every method call and every variable access in Ruby is achieved by sending a message to the instance and receiving a response.

Messages are sent by using the send function (or public_send to not bypass visibility) and passing the symbol with the name of the method you want to invoke, and any arguments that function may require. Ruby also allows you to dynamically define methods using define_method(duh!) and even perform actions when a method is not defined on an object.

str = "DeepSource" str.respond_to? :reverse # true
str.send(:reverse) # "ecruoSpeeD" str.respond_to? :[] # true
str.send(:[], 4..9) # "Source" str.respond_to? :dummy # false

The above examples are the same as what you could achieve by invoking the string’s reverse and split methods. If a class responds to a message, it will perform the action or raise an exception if it doesn’t.

How do I make the most of this? Playing with this message functionality unlocks a whole new world of meta-programming that few other languages can match. You should try to use these features to remove boilerplate from your code and write.

class Person def initialize(name, age) @name = name @age = age end [:name, :age].each do |attr| # Get getters for @name and @age with logging define_method attr do val = instance_variable_get("@#{attr}".to_sym) puts "Accessing `#{attr}` with value #{val}" val end end # Handle missing attribute puts "Person does not #{m.id2name}" end
end person = Person.new("Dhruv", 24)
person.name # "Dhruv" | prints "Accessing `name` with value Dhruv"
person.age # 24 | prints "Accessing `age` with value 24
person.sing # nil | prints "Person does not sing"

Monkey patching

This is perhaps the most controversial but also the most powerful feature of Ruby.

Monkey patching, a play on the phrases “guerrilla patching” and “monkeying about”, is the process of opening up pre-defined classes and changing their existing functionality or adding functionality to them. Ruby as a language is one of the only few that actively encourage the use of monkey patching as a legitimate way to add functionality to the language.

While languages like Python and JavaScript discourage the process, Ruby embraces it and makes it dead easy to extend any class or module as simple as this:

class String def palindrome? self == reverse end
end 'racecar'.palindrome? # true
'arizona'.palindrome? # false

How do I make the most of this? Frameworks like Rails actively use monkey patching to add features to built-in Ruby classes like Stringand Integer. If used carefully and appropriately documented, it is a powerful way of adding functionality in one location and making it available everywhere across the codebase.

Care should be taken to not overdo this and only add the most general purpose code to the root classes.

To drive the point home, feast your eyes on monkey patched code beauty from Rails ActiveSupport. You can install it separately from Rails and see a comprehensive list of examples in theirdocs.

time = '2021-01-01 12:00:00'.to_time # 2020-01-01 13:00:00 +0530
day_prior = time - 1.day # 2019-12-31 13:00:00 +0530
almost_new_year = day_prior.end_of_day # 2019-12-31 23:59:59 +0530
happy_new_year = almost_new_year + 1.second # 2020-01-01 00:00:00 +0530

1.in? [1, 2, 3] # true { sym_key: 'value' }.with_indifferent_access[:sym_key.to_s] # "value"
{ 'str_key' => 'value' }.with_indifferent_access['str_key'.to_sym] # "value"

Less is more

In the pursuit of programmer happiness, Ruby is packed to the brim with syntax sugar and method aliases focused on readability.

How do I make the most of this? You should preferably use shorthand wherever Ruby’s syntax allows it because the reduced punctuation and added conciseness makes the code easier to read and process mentally.

Want to make an arrays of strings, symbols or numbers? Use % notation.

%w[one two three] # ["one", "two", "three"]
%i[one two three] # [:one, :two, :three]

There are uppercase versions of these shorthands that also allow interpolation.

pfx = 'item'
%W[#{pfx}_one #{pfx}_two #{pfx}_three] # ["item_one", "item_two", "item_three"]
%I[#{pfx}_one #{pfx}_two #{pfx}_three] # [:item_one, :item_two, :item_three]

Another interesting shorthand notation is when you’re trying to map or select over an array, and all you want to do is invoke a single method on all of the objects.

strings = %w[one two three]
strings.map &:upcase # ~ strings.map { |str| str.upcase! }

Many of the operations we take for granted in a programming language, like mathematical operations, are all syntax sugar notations! Since Ruby is built on message passing, any valid string is a valid method name such as + or [].

1.+(2) # ~ 1 + 2 words = %w[zero one two three four]
words.[](2) # ~ words[2]
words.<<('five') # ~ words << 2

“Omakase”

Remember the other word I asked you to remember when we started? I promised it was relevant. “Omakase” is an opposite version of an_“okonomi”_ meal, this time consisting of sushi selected for you by the chef. While Ruby’s offer of several ways to accomplish something boosts creativity and expression, it comes with its own set of drawbacks, especially when it comes to consistency and code review.

def is_prime(num) if num >= 2 f = (2...num).select do |i| next num % i == 0 end return f.size == 0 else return false end
end is_prime(0) # false
is_prime(1) # false
is_prime(2) # true
is_prime(3) # true
is_prime(4) # false

class Integer def prime? return false if self < 2 (2...self).none? { |i| self % i == 0 } end
end 0.prime? # false
1.prime? # false
2.prime? # true
3.prime? # true
4.prime? # false

Based on what we’ve leaned, we can make the following changes to the code:

monkey patch method definition into the Integer class
use ? in method names that have a Boolean return type
remove redundant parentheses ( )
exit early instead of indenting the entire code inside an if block
remove redundant return and next keywords
inline blocks with a single expression using braces { }
use from Ruby’s huge assortment built-in functions, such asArray::none?

Using a comprehensive style guide and linter is key when getting started with programming in any new language. Not only does it improve the quality of your code, but it also provides you an excellent way to learn by pointing out improvements in real-time as you code.

A linter will reduce the number of ways you have for writing a program, but what you lose in the creativity of expression is more than made up for inconsistency and code clarity. I would gladly make that trade-off even as a professional, much more so if I were a novice.

Let me recommend two tools that you should use as a beginner.

RuboCop

When it comes to a linter for Ruby, nothing comes even close toRuboCop. It’s a linter, formatted, and style guide rolled into one, and while it is configurable, the configuration that shipped with out-of-the-box is more than enough to put you on the right track for code quality. RuboCop also helps you scan for security vulnerabilities, giving you yet another reason to set it up.

Install and try it out today. Your future self will thank you, and possibly me as well.

DeepSource

Setting up DeepSource for Ruby is extremely easy. As soon as you have it set up, it will scan your entire codebase, find scope for improvements, fix them, and open PRs for those changes.

That’s all folks! Have fun learning Ruby, it’s a fantastic language.

Beginner's guide to JavaScript static code analysis

Saif Sadiq — Mon, 11 Jan 2021 08:35:21 +0000

Do you suffer from poorly written code? Is your codebase riddled with inconsistencies? Do you experience anxiety every time your code is being reviewed? If you answered ‘yes’ to any of these questions, static code analysis could help.

Static code analysis is the process of analyzing code before it is executed. It provides numerous advantages to developers, and integrating static code analyzers can supercharge your developer workflow.

Let’s take a deep dive to understand what static code analysis is, why you should be using it when to start, and how you can quickly set it up in your project.

What is Static Code Analysis?

Of all the questions we just raised, this is probably the easiest to answer. As the name says, Static code analysis is the analysis of code in a static or non-executing state. It is the automated equivalent to another developer reading and reviewing your code, except with the added efficiency, speed, and consistency afforded by a computer that no human could match.

How is it different from testing?

You might be thinking, “If I write detailed tests of all my units and functional tests at a system level, and they all pass, my code is bug-free, right?” Yes, it is. Congratulations. But bug-free code is not the same as good code; there’s a lot more that goes into that. That is the domain where static analysis shines.

All types of tests, be it unit tests, functional tests, integration tests, visual tests, or regression tests, run the code and then compare the outcome against known expected-state outputs to see if everything works OK. Testing makes sure your code functions as expected. It treats your code as a black box, giving it input and verifying the output.

On the other hand, static code analysis analyses its aspects such as readability, consistency, error handling, type checking, and alignment with best practices. Static analysis is not primarily concerned with whether your code provides the expected output but rather with how the code itself is written. It’s an analysis of the quality of source code, not its functionality.

To summarise, testing checks if your code works or not, whereas static analysis checks if it is written well or not. Testing and static analysis are complementary to each other, and you should ideally be employing a healthy mix of both in your projects.

Why use Static Code Analysis?

Any tool that reads the source code, parses it, and suggests improvements is a static code analyzer. There are many tools that fall under the umbrella term of static code analyzers, from linters and formatters to vulnerability scanners and PR reviewers. Let’s go over the main reasons why you should use these in your workflow.

In-depth code scanning

Ask any developer, and they’ll corroborate that code reviews are essential. A second pair of eyes can discover issues in your code you probably never could. They might quite possibly suggest better ways to accomplish the task too. Sometimes reading other people’s code can teach the reviewer about some obscure useful functionality that’s already built into the project. Both the reviewer or the reviewee (which might not be a real word but one I will use nonetheless) learn something in the process.

But what’s better than one person reviewing your code? How about every open-source developer reviewing it! Static analyzers are powered by a vast library of open-source rules, which means that everyone who has contributed to the tool has indirectly reviewed your code. This makes it very hard to subtle bugs that a couple of human reviewers could miss, to slip by.

People make mistakes. Only 15% of codebases that install JSHint, a popular code-review tool for JavaScript, pass without issues. That just goes to show how vital it is to have some computer eyes review your code as well.

Example:

Consider this program for letting the user pick their favourite fruit. If you don’t choose, ‘Mango’ is the default.

let fruits = ['Apple', 'Banana', 'Cherry', 'Mango']
function getFruit(index) { index = index || 3 // Everybody likes mangoes
    return fruits[index]
}

This code works. For all inputs other than 0 that is. If you aren’t very thorough, your tests will also pass without a single hiccup.

getFruit() // Mango
getFruit(2) // Cherry
getFruit(0) // Mango (expected Apple!)

Turns out, you can’t choose an apple in this program because 0, like null and undefined is a falsy value. You should have used the null-coalescing operator (??) instead, and a linter would have told you that.

let fruits = ['Apple', 'Banana', 'Cherry', 'Mango']
function getFruit(index) { index = index ?? 3 // Everybody likes mangoes
    return fruits[index]
}

Guard rails and training wheels

Every developer writes code differently in their own personal style. But when many developers are working together, it is important that they write code in a consistent manner. That’s where a style guide comes in. Setting one up is the first step to writing consistent code, and its enforcement extremely important when working with other developers.

Enforcing a style guide is not a manual feat. No developer can be expected to remember hundreds of rules and check every line against each of them. Why not make the computer do it?

Every language that I’ve ever worked in has a linter written for it. JavaScript has ESLint; Python has Black, and Ruby has RuboCop. These linters do the simple job of making sure your code follows the prescribed set of style rules. A few linters like RuboCop also enforce good practices such as atomic functions and better variable names. Such hints are very often helpful in detecting and fixing bugs before they cause issues in production.

Example:

Consider the following JavaScript snippet where you print a fruit name from a list. The list remains unchanged throughout the program.

var fruits = ['Apple', 'Banana', 'Cherry', 'Mango']
console.log(fruits[0])

ESLint, if so configured, can make sure you use constants wherever possible to avoid side-effects in your code. It’s a good practice but easy to miss if you don’t have a linter.

const fruits = ['Apple', 'Banana', 'Cherry', 'Mango']
console.log(fruits[0])

Enforcing the use of const and let, which are block-scoped, over var leads to programs that are easier to debug and is generally considered a good practice.

Discover issues instantly…

Another thing developers love is testing their code, making sure it holds up for various inputs. Practices like test-driven development emphasize the importance of testing the code that you write. But writing tests takes time and effort. It is hard to gauge every possible input and make sure your code holds up to that. Eventually, tests become too many and take hours to complete on larger codebases.

Static code analyzers do not suffer from this issue. You don’t need to write the tests; you can import entire libraries of presets. Additionally, static analyzers run incredibly fast as there is no code execution involved! In fact, many linters integrate with the editor and highlight issues with the code in real-time as you type.

Example:

Sometimes, real-time is just too fast.

…fix them just as fast

Most static analyzers, especially linters and formatters, will not just point out issues but can also fix most of them for you. Linters like Black for Python and ESLint for JavaScript integrate with IDEs and can then automatically fix the edited files as soon as you save them.

This is extremely convenient because now, your code quality improves without you having to even consciously think about it. As developers, we’re spoilt for convenience, aren’t we?

Example:

ESLint has the --fix flag that fixes common issues like unnecessary semicolons, trailing spaces, and dangling commas.

Consider the same code snippet from the past few examples. (Here the · represents a space.)

var fruits = [ 'Apple', 'Banana', 'Cherry',·· 'Mango'
];

Run ESLint with the --fix flag and moments later you have this.

const fruits = [ 'Apple', 'Banana', 'Cherry', 'Mango',
]

Much better!

Bill of materials

A bill of materials is generally used in supply chain management as the cost of just the raw materials that go into any product. A similar bill of materials is needed for software as well.

When you build an app, you inevitably use frameworks and tools that were built by other developers. In turn, those frameworks use frameworks built by other developers. And before you know it, setting up a simple Vue.js app can put thousands of packages in your node_modules/ directory.

This is the scary reality we live in. Packages built on top of packages. Each giant is standing on the shoulders of another. Your app is only as strong as its weakest dependency. Vulnerability scanners are another set of static analyzers that check every dependency in your dependency tree against an extensive database of vulnerabilities and exploits. All packages that have a known vulnerability are reported and can be updated with a single command.

Example:

GitHub provides dependency scanning with Dependabot. npm also provides a vulnerability scan using the npm audit command. Both Dependabot and npm audit offers the ability to automatically update vulnerable packages to their patched versions.

Automate the boring stuff

Manual code reviews waste a lot of time. The person doing the review has to take time out of their own work to do the review, go through the code, and point out all the different places where it could be improved, both logically but also in the tiny details such as incorrect formatting or deviation from conventions and style guides. Then the reviewer has to make all the suggested changes and repeat the process.

Adding some linters, formatters, and spell checkers make the entire process much more streamlined. How so, you ask? First, a pre-commit hook will ensure that code is properly linted and formatted before getting checked-in to VCS. Second, project-level automation in the form of build pipelines or GitHub workflows will test the code quality on every commit and highlight issues on the PR itself. Third, the reviewer will be freed up to focus on the big picture because all the smaller things have already been handled before the PR makes it to a manual review.

No amount of code review by software can entire replace manual review. But a static scan before a manual review can easily augment both the reviewer’s experience by reducing their effort and getting the developer’s code reviewed by iterating on the smaller issues faster and more thoroughly than many rounds of manual reviews.

The When

Now. Yes, that’s correct. I did say right now. Any later than right now is too late. You would have reached step two of ‘The How’ if I didn’t have to convince you as much.

The How

Setting up is easy. Since we’ve repeatedly been talking about ESLint here, let’s just set it up in a sample project.

Make a new project

Make a new directory for your project. Enter the directory and initialise a Node.js package in the directory. The npm init wizard asks you a series of questions. Once you’re done, you have a new Node.js package to work in.

$ mkdir wuphf.com
$ cd wuphf.com
$ npm init

Install ESLint

Install ESLint. It’s too simple.

$ npm install eslint

Configure ESLint

Run the following command to bring up the ESLint wizard.

$ ./node_modules/.bin/eslint --init

This wizard asks a lot of questions about the how you will be using ESLint in the project. Make sure to choose the Airbnb ruleset. When the setup is complete, will will have a file .eslintrc.js in the directory.

This file defines that the project will be running on Node.js and it will be building on top of the rules defined in the Airbnb style guide. Since we’re writing a console application, I can customise the rules and turn off the one that warns against it.

module.exports = { env: { es2021: true, node: true, }, extends: ['airbnb-base',], parserOptions: { ecmaVersion: 12, }, overrides: [{ files: ['*.js'], rules: { 'no-console': 'off', }, }, ],
};

Commit this file into version control.

There you have it! All JS file in the project will now be continuously scanned by ESLint. I also recommend install Husky to run a lint job before every commit so that you never check in poor code into your VCS ever.

Automate everything with DeepSource

DeepSource is a static code analyzer that can find issues in the codebase and automatically submit PRs to fix them. It can even evaluate incoming code in PRs and fix them too. It’s wonderful how well it integrates with GitHub, GitLab, and Bitbucket.

You can set up DeepSource in a project by dropping a single TOML file named .deepsource.toml in the root of the repo and it will pick the project up and start scanning. Most major languages are supported.

The End

That is all. It’s really simple to statically analyze your code, and the benefits are so many that there’s no reason not to be doing it.

Have fun writing cleaner, safer, more readable, and more maintainable (simply put, better) code, and we’ll see you in the next one.

Using state machine to write bug-free code

Saif Sadiq — Tue, 29 Dec 2020 11:32:36 +0000

The first time you heard of a state machine, what did you think it was? I thought it was a debugger. A debugger I could use to find those annoying bugs in my code. A state machine is not a debugger. However, when you master how to use a state machine, the code you write would be on the bug-free side.

What is a State Machine?

A state machine is an abstract concept that defines and plans the stages and transitions of an application. The application only transitions upon the occurrence of an event. A state machine indicates the initial state of an app, for example, and what would be the next stage – transition – if a user uses the app.

For example, in a functioning Automated Teller Machine (ATM), where you can insert your card, it displays a message like welcome on its screen. That is how the programmer who programmed the ATM designed the initial state of the machine. Once you insert your card, the ATM changes its display and asks for your password. By inserting your card, the ATM transitions to another state. If you enter the right password, the ATM displays its services – withdraw, account balance, transfer, and so on. Each ATM services is a state the ATM could transition.

By clicking on a service rendered by the ATM, it transitions to another state - where you can either withdraw or transfer funds or check your account balance. It depends on what you click.

If you enter the wrong password, the ATM changes to another state that says “sorry, you enter the wrong password” or something like that.

The programmer has planned every state and transition of the ATM. That means if user A, for example, clicks a button on the ATM, the machine changes to a particular state.

Of recent, I wanted to access my account on a platform through Google Chrome. I entered my username and password. The website sent a One Time Code (OTP) to my phone number to ensure I was the person trying to login. When I clicked Sign in, the app moved from the sign-in page and threw a bug – it displayed a blank page. There was no place I could enter the code.

Having a planned state machine would have solved the bug. In an instance where the state machine had been well planned, once you click sign-in and you receive the code on your phone, the next page should either be a page having an empty box where you can enter the code or raise an error and direct you back to the sign-in page.

That is how a state machine helps you write bug-free code. The code you write would have envisaged each state of the code, what makes it transition, and to what state.

How to Design State Machine to Write a Bug-free Code

The reason why you have bugs in software is as a result of an input sent to the wrong state. Remember my account login details sent to a blank page? That was because of an inefficient state machine.

To avoid such bugs, here are steps on how to design a well-planned state machine.

1. Identify initial state

Before you write a code, identify the first state of your application when it becomes a finished product. As an example, initial states like sign-in and or register page. The initial state in the diagram below is the idle state. The idle state could be the sign-in or register state or both. You should first identify the initial stage when the code you write becomes a finished product.

2. Identify events

Events are what cause an application to move from a state to another – transition. Events could be anything resulting in changes – input, clicks, camera caption, and more. For example, you ordered goods on an e-commerce website; the website takes you to a page where you can request shipping of the goods. On that same page, there is also an option to cancel your order. Ordering the goods or canceling the order is an event.

Identify each event that could make your application transition; this makes your code bug-free. You would have programmed your code to allow specific actions: whether to take a user to the next page or stage - or throw an error message and take a user back to the previous state.

3. Determine transition

Map out each state your application would be when an input or an action occurs. When a user uses your app, what are the stages the app could move? For instance, you programmed a web application that allows users to borrow books. The first state of the application displays a search box where a user can search for the names of books. If a user enters the name of a book, the app either takes the user to the page where the book is or displays: sorry, the book is not found or on loan. These are transitions - an application moving from one predetermined state to another because of an event.

However, there is an issue a state machine should solve in the above example. What happens if a user enters the name of the book he is looking for and press the search button; while the app is still processing the search, the user inputted a name of a different book and pressed the search button again?

In this case, a code having a well-planned state machine would make the second search ineffective till the first search completes. A state machine you planned based on each state helps you identify bugs and also puts you in control.

Why State Machine Needs to Be Designed From a State Perspective and Not Transition

Design a state machine based on the states an application would fall in; such an application does not run into bugs. The design would consider each state the application would be, and each event that should occur before there is a transition. By this, a programmer writes a lesser code and is in control of its application. An application will only carry out functions it is programmed to do and reject everything else.

More so, a code would achieve the business logic behind it. The code, in a strict sense, achieves its aim. Take a book reader app as an example. The book reader allows users to store and read books in it. That is the business logic behind the creation of the app. To make people keep and read books on it.

You write long codes in a state machine designed from a transition perspective. Your code would use a lot of conditions trying to accommodate all possible actions a user could take. Along the line, you may lose control and focus on why you’re writing a code. Your application risks running into many bugs. Transitions are, most times, unknown at the beginning. The best is to determine the states of your app.

Conclusion

A state machine defines and plans the stages of an application. It is planning a code on how it should work. A state machine ensures a code is bug-free. It also makes sure the business logic behind writing it is achieved.

DEV Community: DeepSource

JavaScript best practices to improve code quality

1. Block scored declarations

2. Arrow functions

3. Optional chaining

4. Null-ish coalescing

5. Logical assignment

6. Named capture groups

7. async & await

Guidelines for Java code reviews

1. Follow Java code conventions

2. Replace imperative code with lambdas and streams

3. Beware of the NullPointerException

4. Directly assigning references from client code to a field

5. Handle exceptions with care

6. Ponder over the choice of data structures

7. Think twice before you expose

8. Code to interfaces

9. Don’t force fit interfaces

10. Override hashCode when overriding equals

Python code review checklist

Code review checklist

Etiquettes

Functionality and syntax

Design

Patterns and idioms

Readability

Documentation and maintainability

Security

Performance, reliability and scalability

DeepSource

The ideal code review

Common anti-patterns in Go

What are anti-patterns? 🤔

1. Returning value of unexported type from an exported function

2. Unnecessary use of blank identifier

3. Using loop/multiple appends to concatenate two slices

4. Redundant arguments in make calls

5. Useless return in functions

6. Useless break statements in switch

7. Not using helper functions for common tasks

8. Redundant nil checks on slices

9. Too complex function literals

10. Using select statement with a single case

11. context.Context should be the first param of the function

Breaking builds, baseball bats, and the code quality DNA

The Microsoft executive who alarmed everyone with a baseball bat

Slow down today and move 10X faster tomorrow onwards

The similarity between pilots and programmers

5 Common mistakes in Go

1. Infinite recursive call

2. Assignment to nil map

3. Method modifies receiver

4. Possibly undesired value being used in goroutine

5. Deferring Close before checking for a possible error

Leveraging static code analysis in a Ruby CI pipeline

Prerequisites

Creating a sandbox

Setting up Ruby and Bundler

Getting familiar with Rubocop

The code

Pipeline

Picking the infrastructure

Adding lint workflow

Fixing problems

Staying clean

DeepSource

Automate the tedium away

Automate code formatting in Python

Ingredients

A. Codebase with PEP-8 violations

B. Black code formatter

Recipe

1. Set up Git hooks

2. Lint check using GitHub Actions

3. Lint fixes using GitHub Workflows

End-to-end automation with DeepSource

Finis coronat opus

Common Python security pitfalls, and how to avoid them

Problems and solutions

7. `async` & `await`

3. Beware of the `NullPointerException`

3. Using loop/multiple `append`s to concatenate two slices

4. Redundant arguments in `make` calls

5. Useless `return` in functions

6. Useless `break` statements in `switch`

8. Redundant `nil` checks on slices

10. Using `select` statement with a single case

2. Assignment to `nil` map

5. Deferring `Close` before checking for a possible error