Code Reviews

2022-03-21T00:00:00+00:00

Last week, a few End Point team members and I came together to prepare a presentation on code reviews for the whole company. We went through the basics of “what”, “why”, and “how”.

We also, and perhaps most interestingly, made several recommendations that we’ve discovered after years of doing code reviews in a variety of teams and project sizes. A series of “lessons learned” so to speak.

I thought it’d be useful to capture that discussion in written form. Let’s start with the basics.

What is a code review?

Wikipedia’s article on code reviews says that a code review is…

A software quality assurance activity in which one or several people check a program mainly by viewing and reading parts of its source code, and they do so after implementation or as an interruption of implementation.

That is a precise but frankly wordy way to say “having somebody look at the code you’ve written”. This definition, however, touches on a few aspects that give us good insight into what code reviews are and what their purpose is.

First up, it tells us that code reviews are a software quality assurance activity. That is, their main goal is to make sure that the code that’s being produced is of good quality.

Second, it tells us that they are carried out by one or several people, revealing that code reviews are a team exercise. It’s the opposite of coding in isolation. Coding becomes a communal task, with input from other team members.

It also tells us, maybe unsurprisingly, that the main focus of the review is the code itself. As the main deliverable artifact of the software development process, we should strive to make it as good as possible.

Finally, it tells us when code reviews should happen: when implementation is done, or there’s a logical interruption of it. Meaning, once a feature is done, a user story is complete, a bug fixed. That is, when there’s a cohesive chunk of code that has been written.

Why should we do code reviews?

So why are code reviews important? They provide many benefits.

First and foremost, code reviews can help improve the code’s internal quality. Productive discussion around an implementation can help improve maintainability and readability of the code when reviewers, with a fresh set of eyes, spot the potential for such improvements where the original author may have missed them.

Also, and just as important, external quality of the code can be improved. Reviewers can help find bugs or other types of defects like security and performance issues.

Code reviews can also serve as a knowledge sharing tool. Code written by team members of more seniority or who are more knowledgeable about the code area, business domain, or a specific tool or library, can be exemplary for other team members. They can learn from the code when conducting reviews. This has the added perk that it reduces the situations where a single person holds all the knowledge of a given system component or code area. Likewise, code review feedback provided by such an expert can have the same effect.

Another great benefit they can bring to the table is the distribution of code ownership among all of the team members, not only the author of the code in question. When projects have strong code review habits, the code becomes something that the whole team is producing, as every line that gets to production has been seen by, and incorporated input from, many of the members of the team. Everybody owns and can feel proud of the final product.

Finally, reviewers can sometimes just come up with better and/or simpler solutions than the ones the original author implemented. They can come up with these given their fresh perspective and maybe their experience with similar problems in other domains. Code reviews allow for these to be incorporated before the time comes to ship the code.

What should reviewers look for?

Simply put, reviewers should look at every aspect of the code and offer suggestions for improvements where they see fit. Google’s recommended practices compile a somewhat comprehensive list of the elements that reviewers should look for:

Design: Is the code well-designed and appropriate for the system?
Functionality: Does the code implement the requirements correctly?
Complexity: Could the code be made simpler? Is it understandable?
Tests: Does the code have correct and well-designed automated tests?
Naming: Are clear names for variables, classes, methods, etc. being used?
Comments: Are the comments clear, useful and necessary?
Style: Does the code follow the project’s style guide?
Documentation: Did the relevant documentation also get updated? Any public interface documentation or OpenAPI files for example.

When it comes to code style, something to note is that this is where tools like linters are prettiers can be implemented to reduce human labor. Early in the project, if the team decides on the style, such a tool can be setup to automate the process of making sure that all code that gets written complies with the style guide. Some code repositories even allow for such tools to be automatically run upon every push. This makes style guide compliance not even a concern for the reviewers, because the tooling always makes sure that the code does comply.

Who should review code?
Who should ask for their code to be reviewed?

Everybody in the team should be regularly reviewing code and having their code reviewed. Regardless of seniority or experience in the specific project area, domain, framework, or language. More “junior” team members benefit from reviewing code by learning new techniques, principles, technologies, and the code base itself. More “senior” team members can provide valuable input that improves the code base and other team members’ skills.

We also have to realize that the distinction between “junior” and “senior” is often blurry. Most teams have people with a variety of skill sets and experience; so everybody has the ability to offer good insight. One can always be a “senior” in one aspect of the project, and a “junior” in another.

Even if a single reviewer can be good enough, it is beneficial to include as many reviewers as possible, lest we fall into the trap of overloading a small number of individuals by having them be in charge of most or all of the reviews. Also, like I mentioned before, two great benefits that code reviews offer are knowledge sharing and code ownership. The more people you have regularly reviewing code, the bigger they impact will they have in these two aspects.

That said, it is always better to have somebody more experienced in the area of the code that’s changing be among the reviewers.

When should code be reviewed?

As Wikipedia’s definition revealed, it is ideal for code reviews to be done when implementation is done on a feature; before merging the new code into the main development branch. Most modern software development that uses a Git-based code repository uses something like GitHub’s Pull Request mechanism. (GitLab uses Merge Request instead of Pull Request: same concept, different terminology.)

The developer creates a Pull Request when they are done implementing a feature or fixing a bug. The PR compiles all the changes (a series of commits) and turns them into a nice digestible package. This adds great visibility to the changes and makes them very easy to review before merging. Ideally, no patch makes it into the system without first being reviewed.

Code reviews can also happen before the implementation is done. Maybe the developer wants to get the team’s input on a specific function, method, class, component or approach. If the developer asks for it specifically, it can happen at any point in their development process.

Some recommendations

Now that we’ve gone over the basics, let’s discuss some recommendations and pitfalls to avoid, inspired by our experience in conducting code reviews over the years.

Keep pull requests to a manageable size

Bigger patches make code reviews harder to perform because of the sheer volume of code that the reviewers need to work through. More code to read makes it tempting to skim over it rather than reading in depth, and makes it hard to gain a thorough understanding of the changes and offer good insight.

So we feel like it is best to keep them as small as possible. This desire to keep things small may need to affect the overall software development process upstream. For example, making sure user stories or change requests are granular enough so that they can be fulfilled with a reasonable amount of code changes. Consider splitting bigger features into smaller, bite-sized issues to make this possible.

Make the pull request cohesive

PRs are better when their size is manageable, but also we need to make sure that they contain all they need to allow the reviewers to understand them completely and as a whole. There’s no need to split the changes artificially (for example, between back-end and front-end) if ultimately, they need to be pushed together to fulfill the requirement that’s being worked on, and leave the system in a working state.

If you would like a preliminary review, ask specific questions

Sometimes we want to get early reviews even before the implementation is complete or we’re at a logical interruption point. For such cases, a good practice is to come to the reviewers with a specific question that we’d like them to focus on.

It can waste time if the intent of the review is not explicitly communicated: The reviewer could mistakenly do a thorough review and leave feedback on tiny details of code that’s not yet ready and not even address the specific larger aspects that the developer wants help with.

Pair programming has the first code review baked in

Pair programming can expedite the review process by closing the code review feedback loop, compressing it to its fastest form. In pair programming, code effectively gets reviewed as soon as it is written, bit by bit.

If the team has more than two developers, though, there’s still great value in having the other team members, the ones not involved in the pair programming activity, review the code. They will approach it later with fresh eyes and without the shared mental context the pair had.

Code reviews work well asynchronously

In general, don’t make code reviews a synchronous process. Publicly available Git repository cloud hosting services like GitHub and GitLab include great tools for reviewing pull/merge requests. We should use them to their full potential. There’s no need for a conference call or an in person meeting where everybody blocks a chunk of time to dedicate it to reviewing a PR. Everybody can do it on their own at their convenience.

But if a member of the team is new to the process of reviewing code, it can be good to work through a few pull requests at the same time, together, till they get the hang of it.

Give code reviews high priority

Give code reviews a high priority within your daily tasks. It is counterproductive to let pull requests sit for a long time when a few minutes to an hour of our time can mean that a user story/ticket can move forward through the process. If you work by organizing your increments via sprints, remember that the goal is to complete the most stories as a team. Reviewing a pull request is actively supporting that goal, even if it isn’t one of the stories/issues you’re working on yourself.

Make sure your PRs get the attention they need

Don’t just “fire and forget” a pull request. If it happens that any of our patches are taking too long to be seen by other people, we don’t just abandon them and think that they are somebody else’s problem now, that our work is done. In these cases we should feel free to reach out to the reviewers and bring the PRs to their attention.

To this end, we should leverage all the communication tools available, even outside of the code repository or code review tool, by chat, phone, issue tracking system, etc.

Get as many reviewers as you can

A single reviewer on a pull request can be enough. However, it is always beneficial to try to get as many eyes as possible onto a change. It improves ownership and it allows for more effective knowledge sharing. It also has the potential for more improvements on the code base, as more people, with varying strengths, look at the code and offer their feedback.

Also try to avoid having a single person be the gatekeeper of merges. Like I said, everybody can and should participate in the activity of code reviews. Sometimes having a gatekeeper this may be desirable if, for example, CI/CD is in place in such a way that merges produce automatic production deployments. But we can always try to make sure that code that reaches the gatekeeper is already reviewed by other team members by the time it does. That way we avoid overloading them and eliminate the bottleneck or single point of failure.

GitHub, GitLab, and similar tools provide settings to limit which users can commit to certain branches. If a process like that is needed, it can be done with help of such tools while still having PRs that many team members can review and discuss.

Don’t let the perfect be the enemy of the good

If the PR isn’t “perfect” or not “as good as it could be”, but it does not worsen the code base, and implements the changes competently, maybe there’s no need to block it. Code reviews are important, but it also is important to try to maintain momentum of delivery and avoid making developers feel nitpicked. So consider that when reviewing. There is a balancing act between deadlines, paying off and incurring technical debt, and what is “good enough”.

In the same train of thought, it is useful to clearly label code review comments. Specifying whether the reviewer considers each comment as a question, a simple nitpick, or an actually important change.

Top-down imposition of process is often inconvenient

Code reviews don’t need to include a ton of software process overhead. Regardless of your process style, it can be a very lightweight practice and done at the developers’ discretion. It can be as simple as sending a diff file to a fellow developer and asking them for feedback. The tools available today make them very accessible and easy to do.

As such, they can become very effective when the team itself manages and conducts them; as opposed to having it come to them as a predetermined specific process from management. Even a practice as beneficial as code reviews can be soured by a bad, overly strict, or dogmatic implementation.

That’s all for now

At the end of the day, the concept of code reviews is simple: To have somebody else look at our code, in hopes that what eventually makes it to production is as good quality as possible.

In this article we’ve discussed many more aspects to clearly explain the promise of code reviews. We’ve given some details on how to conduct them, who is involved, and what benefits we can get from them. We also captured a series of recommendations that we have learned through experience.

If you’re not into the habit yet, hopefully this article convinced you to give it a try!

Engineering Is Not Just About the Cool Stacks

2021-05-25T00:00:00+00:00

Photo by Di

As a developer, I love finding new shiny pieces of tech that can help me develop web applications better. To me, it is one of the best parts of the job: Pick up a new programming language, a new database, a new standard, etc., and build cool things with it. But recently, I had the chance to reflect on my experience working on a boring stack at one of my previous workplaces, and it was actually a lot better than I expected.

My journey

I used to work at a company where the teams are free to decide the tech stacks that best fit their requirements, so a wide range of modern tools were used there to solve the problems at hand. Within just 2 years of joining the company, I switched teams four times and touched everything from Java, Scala, Akka, Terraform, AWS ECS, Serverless, API Gateway, AWS Lambda, AWS DynamoDB, React, Gatsby, Vue, Nuxt, TypeScript, Flowtype, and many other tools that really helped advance my technical skills.

But in late 2018, my manager invited me to assist a “less popular” team in the company. The team handled a myriad of complex products that are quite old. The team’s tech stack was not the shiniest compared to the other teams in the company; the products are developed using Java, a language I generally do not prefer due to its verbosity. We just shipped JAR files to the platform’s marketplace, so there were no web services to maintain and hence it didn’t challenge or sharpen our operations skills. The frontend JavaScript code was largely built with jQuery as it came bundled with the platform we are building on top of.

As a developer who loves shiny tools, this team should have been a dreadful one to be in. But to my surprise, as I reflect upon it, it was actually the team that gave me the highest work satisfaction. It was satisfying because there were a lot of problems to solve, and most of the time the harder problems to solve are not the tech stack: the apps work, and customers are paying.

Instead of talking about moving from Java to Kotlin or from jQuery to React, our team spent the time brainstorming ideas on how to increase code quality, how to ensure discipline and follow good principles when crafting software, how to improve our developers’ workflow and processes, and how to best share knowledge and contexts that we had just acquired for future team members. Each problem solved gave me that dopamine boost that made me feel good.

Below are some of the things we did to solve these problems.

Problem #1: Code quality

The products the team were handling had been suffering from some quality degradations in recent years, and these ultimately led to more bugs and regressions, which then leads to an increase in customer complaints, and that leads to us working under pressure, which then leads to even more quality degradations, and the vicious cycle repeats.

When this started to happen, what did we do?

We slowed things down. Instead of having individual engineers work on multiple tickets in parallel, we held more pair programming sessions and reduced the number of tickets in progress to help incorporate collaboration earlier and gain feedbacks on the implementation strategy sooner. At the same time, pairing sessions also helped get the newer engineers up to speed faster. We introduced more quality gates for pull requests to be able to be merged into main. We agreed as a team to scrutinize them harder, e.g. if you do not have tests among the changes, just consider the pull request rejected. We also required all team members to approve the changes. We worked with product managers to slow down shipping new features and instead having more bugs fixed. Hence, the health of the codebases got better and better and the products got more and more stable each day.

We also held a brown-bag meeting reinforcing SOLID design principles to everyone in the team. Knowledge sharing like this helps bring everyone onto the same page while pairing and reduce the long discussion threads on pull requests.

Members of a team come and go, and that is true for all teams. Complex apps like the ones we were maintaining are usually full of legacy decisions that the newer team members will not have the knowledge of if no deliberate efforts were made to ensure that those contexts get shared. So, we took steps to mitigate this by including the contexts in commit messages. We also encouraged writing our findings in the Jira tickets and in the pull request descriptions on GitHub, but we preferred Git commit messages for documenting decisions related to the commit, because Git is the system that is least likely to change. We might switch from Jira or from GitHub to some similar services, so contexts would be lost when that happens, but it is very unlikely that we would switch from Git for version control.

We also started a knowledgebase to contain information that should be shared within the team, including onboarding instructions, development gotchas, legacy contexts, etc. This helps distribute the knowledge to everyone and reduce blockers on specific team members. We also made a habit of documenting a discussion that happens offline, often in our internal communication channels or in our internal knowledgebase.

Problem #3: Developers’ workflow

Improving our process was also a focus. One of the first things we did was rewrite our Jenkins CI/CD pipeline to adopt multibranch pipeline, allowing us to build and test feature branches before they were merged into the main branch.

We also automated several tasks that we identified as repetitive, from as small as notifying everyone that there is a new pull request open on GitHub, to automatically running compatibility checks for all of our products once the platform we were building on released a new beta version. We constantly looked for areas we could automate better and discussed them in our weekly retrospectives.

We also tuned our workflow to better organize our capacity around all the demands that we are getting: from our customers, our roadmaps, and our improvements bucket. We adopted Classes of Service (CoS) to achieve that. CoS is an approach in which you decide different treatments to different types of work. This means the capacity we have is flexible depending on the demand of each type of work.

For example, we introduced a collapsible task buffer called Intangible that holds work whose value customers do not experience directly, such as upgrading Node.js version, etc. It is collapsible in the sense that the developers in this CoS can be reassigned to other CoS should we deem more capacity is required there. Note that CoS (or any other system for that matter) is not without its pros and cons, so be sure to tweak it to fit your circumstances should you consider adopting it.

Not all problems are tech, but all tech has problems.

Sometimes, we identify ourselves through our favorite tech stack.

Hey, I’m a JavaScript developer.

Hey, I’m a Ruby developer.

And that is not wrong per se, but this particular experience of mine serves as a reminder that the essence of software engineering goes deeper than just the tech — it is to solve problems through software. And that is what we do at End Point.

Reference

SOLID Design Principles at Devopedia
Classes of Service:
- On Classes of Service (CoS), a more pragmatic approach towards “squad formation” by Yuen-Chi Lian at ServiceRocket
- Predictability and Classes of Service by Leonardo Campos at ThoughtWorks

End Point Security Tips: Securing your Infrastructure

2020-02-05T00:00:00+00:00

Photo from comparitech.com

Implement Security Measures to Protect Your Organization & Employees

In this post, I’ll address what I believe are the three important initiatives every organization should implement to protect your organization and employees:

Train employees on security culture.
Implement the best technical tools to aid with organizational security.
Implement recovery tools in case you need to recover from a security breach.

Habits of a Security Culture

Train everyone in your organization on these fundamentals:

The only time you should be requested to reset your password by email is when you initiate it. There are rare exceptions to this rule, such as when accounts are compromised and providers request all users reset their passwords, but those events should be publicly announced. Staff can confirm with security personnel before acting on such requests.
If you are asked to reset your password, it will typically be after you successfully logged into a website and the old one has expired.
If you receive an email and do not know the sender, do not trust the contents or open attachments. Get advice from security personnel if needed.
If you think the email is from your bank, keep in mind that banks do not ask their clients for private information via email.
If you think the social security office emailed you to obtain your personal information, keep in mind that they do not initiate or solicit private information via email.
Companies should not solicit private information unless you initiate first.
Online retailers should not ask for your private information unless you initiate first.

A Security Concern: Going Phishing!

Photo by Epic Top 10 Site

One of the more common ways to steal someone’s private information is through phishing. Phishing is like fishing: you try to catch something. In this case, the ‘fish’ is your data. Someone with malicious intent sends you email to attempt to get you to click on the link, picture, content, etc. within the email. Once you click the link or content within the email, it might take you to a website to enter or reset your password, even ask for your social security number or other personal information. The person with malicious intent would use the information collect to open accounts, purchase items online or resell your personal data. The links within the phishing email might even redirect you to a fake website that mimics a real website to collect your personal data. The goal is to confuse the email recipient into believing that the email message is legit in its attempt to collect personal information from the user.

Phishing Exercises

Photo by Christiaan Colen

One way to help the staff better their understanding of a phishing email is to practice phishing exercises by setting up an experiment to see which users would click on your test phishing email. If the user clicks on the experiment phishing email, the email administrator would notify the compliance officer and he or she would re-train the staff on how to properly differentiate real emails from phishing emails. Phishing exercises make a great activity for the employees to avoid the email scams and exert more caution in the future.

Essential Security Tools

Firewall

A firewall should be a mandatory technology for all consumers or businesses. This is basically your main door. The office or organization’s technology is what the firewall is protecting. When you sit in your office working on the computer, just imagine that you are in a fort surrounded by walls. If someone needs to come in, they must be given permission by a gatekeeper to enter the fort. The firewall is very similar. The firewall allows network traffic to go in and out of the office based on the configuration set by a network engineer. The engineer determines what network traffic comes into the office and goes out.

Companies typically test their firewall with penetration tests and network scans to determine if there are any security concerns after implementing the firewall. The testing of the firewall verifies that good security practices are implemented and the firewall is setup properly and securely.

Some hardware firewall devices to consider include:

Network Assessment & Internal Threat Protection

Why is security vulnerability testing necessary? Many organizations have legacy servers, or desktops/laptops with operating systems that are no longer supported. For example, outdated Microsoft Windows XP and 7 can be compromised by malware while browsing the Internet due to the BlueKeep vulnerability. Systems that are not patched could expose your organization to be infected with malware such as ransomware which would hold your data ransom until you pay to unlock the data.

Security vulnerability testing typically results in a report outlining problematic areas such as outdated operating systems, private data that does not belong on a file server, such as social security or credit card number (personally identifying information, or PII). If PII is needed for the organization to operate, then higher security standards and an encryption system to store the private data is needed. The security vulnerabilities testing could also check if your environment is HIPAA or PCI DSS compliant if those security standards apply to you.

Some security vulnerability testing technology includes:

Enterprise Antivirus Systems

Antivirus software is the last line of defense if malware enters your computer. The antivirus itself would not protect you 100% from being infected by malware or virus but if you have multiple layers of security in place, then the chances are much lower that your organization’s systems would not be compromised. A company called AV-Comparatives assessed some of the popular antivirus software in the market.

The battle with malware is endless. Case in point: The WannaCry malware affected over 200,000 machines across the world and spread quickly. Security researchers quickly realized the malware was spreading like a computer worm, across computers and over the network, using the Windows SMB protocol.

New variants of viruses and malware are developed every day, so the antivirus companies are also daily hard at work developing a way to block and remove malware.

Some antivirus software includes:

Web Filtering Technology

Web filtering technology blocks websites that are malicious or deemed not appropriate to visit from an organization’s network. For example, websites for gambling could be blocked to reduce employee distractions, but also to reduce access to sites popularly infected with malware, reducing the possibility of malware coming into your network.

There are many competitors out there in this competitive market, and some vendors offer free proof-of-concept testing with their product before you make a big investment. Take a look at:

Data Loss Prevention

Employees’ and businesses’ private information is sensitive and should be protected. Businesses, whether audited or not, should always protect their employee private information. 20 years ago paper was used to store private information and locked in a file cabinet, but in 2020 most private information is stored digitally. How do companies keep private information from leaving their office?

Physically you probably can’t stop someone from walking out with private information, but digitally there is technology called digital loss prevention (DLP) that can help keep confidential information from leaving the office. For example, if someone in the office decides to copy private information onto USB storage, or tries to send a social security number or credit card information via email, this can often be prevented. Prepare your business with solutions tailored for regulations involving personal information using DLP software.

Some DLP solutions to consider include:

Email Filtering

Probably one of the easiest and oldest methods to infect or phish someone is via email. There are multiple mechanisms email filtering uses to stop malicious emails: SPF and DKIM, blacklists, etc. On top of these configurable items, email filtering software vendors often release updates throughout the day to block the latest known malware or spam based on heuristics.

Cloud email services such as Microsoft Office 365 are for many businesses superior to on-premise email servers due to having all the bells and whistles to proactively protect your email environment, such as spam & virus filtering, and email archiving for retention purposes. If you need email encryption to protect sensitive emails, this feature is also available.

The distinct advantage of using hosted email service is that the cost is predictable and includes maintenance, so your email administrators do not have to worry about updating the email server software or hardware.

Email filtering technology available includes:

Two Factor Authentication (2FA)

Companies like Duo (owned by Cisco) and Google’s two-factor authentication technology are great tools to implement to improve your overall security. Beyond the usual user name and password, your smartphone or a hardware token are used to authorize the access to a website, an application, or a network. This technology is now well-established and available in most online services, and can be added to your own custom business applications.

Some starting points:

VPN (Virtual Private Network)

Virtual private network technology allows businesses to provide secure access to office systems or applications to employees who travel or work from a remote location. That is important so that data traveling to and from the source, and many details of traffic patterns, are encrypted, so that the data cannot be captured and decrypted. VPN solutions have been around for years and are an important tool to securely and safely protect data in transit.

Password Reset Systems

Why are self-service password reset systems necessary, and are they secure? They eliminate many manual password assignment mistakes, keep passwords private to the user alone, and allow an organization to integrate two-factor authentication to securely reset user passwords, such as Active Directory for Windows, or other single sign-on password. Onboarding is needed for each user, which is done by sending them an email with a link to register.

The password reset system could be an internal system only available to your organization. Another possibility is to access the system via VPN or even through a proxy server in the DMZ to allow password reset from anywhere.

Some password reset systems include:

Recovery Tools

Data and System Backups/Disaster Recovery

Data backup and disaster recovery practice is a critical component for a business to speed up the process of recovery if malware attacks your systems or if a system becomes inoperable.

If you are attacked by ransomware and all the critical systems and desktops are compromised and rendered useless, then the only way to recover is from backups. At that point, the disaster recovery preparation you made will be well worth what you invested into it. If you did not have an adequate backup or disaster recovery plan, your organization or company would have to start from scratch and rebuild all systems and desktops which could take weeks if not months to recover from. The lost wages, and possibly clients, due to unavailable systems and desktop to operate, probably would cost you far more than preparation does. The more options you have, the better the chances that you will get out of your bind and not prolong the situation.

Some backup solutions I have worked with have the flexibility to mix and match to fit your configuration needs:

Acronis Cloud Backup allows you to back up to local storage, the cloud, and off-premise, recover a system using a USB drive, back up Office 365 emails, or backup VMware or Hyper-V environments. It also allows you to recover a single file if needed.

Additional Security Recommendations

SSL/TLS Certificates

What are SSL and TLS? SSL is outdated and replaced by TLS, but people often still use the familiar SSL name. They are an encryption system to keep sensitive information sent across the Internet encrypted so that only the intended recipient can access it.

When an SSL certificate is validated, the transmitted data is not only unreadable by anyone except for the intended server, but you are relatively well assured you are communicating with the organization you expected and not with a malicious intermediary. Read more details in SSL Shopper’s Why SSL? article.

SSL certificates were historically used primarily for higher-security web servers, but now are commonly used on almost all web servers. They are also used for other remote server access, B2B server-to-server communication, VPN access, email systems, etc.

Recent Destructive Incidents

These incidents from just a few weeks in fall 2019 show that we have a long way to go in protecting our technology usage:

Speak With Us!

Keeping up with security can be a full-time job. If you need professional consulting on security tools and implementing them, contact our team today.

Reviewing the Code

2019-11-26T00:00:00+00:00

Code review is analysis of source code of a software project by reading the code itself or sometimes using automated tools to analyze it, and it is part of the Software Quality Assurance (SQA) activities which define the quality assurance of the whole software development lifecycle.

As we go through the flow of a code-review, we’ll understand what to assure by doing code review. Code review lifecycle covers the guidelines and the code review process itself.

Code review guidelines

Preparing for code review

Pick the right reviewers. The reviewer should be an experienced software architect. Sometimes, less experienced groups can join the review team. Communication is also important, since frequent round table code review meetings with the developers are not usually productive.
Let authors annotate the code before review indicating which files have precedence for review. Annotation by the developers to orient the reviewer so they know where changes have taken place and where to review is a good practice.
Request code review. Requesting code review just before testing is another good practice.

Tips for reviewer during the code review

Review small pieces of code at a time, for instance around 400 lines of code.
Review for around 60 minutes at a time.
Set goals and metrics.
Use SMART criteria:

Specific: target one area clearly and precisely.

Measurable: quantify progress toward success by using metrics.

Actionable: ready to start and possible to accomplish.

Relevant: connected to what’s being done, considered, and/or resourced.

Timely: occurring at a favorable or useful time and opportune.

Measure inspection rate and defect rate.
Use checklists.

Code review flow

Regardless of what programming language is used to develop, code review should cover the following common areas:

Maintainability
Reusability
Performance
Security
Bug analysis
Knowledge sharing

Other practices can also be reviewed, like extensibility or OOP (Object Oriented Programming) software design patterns. These depend on possible future plans and the nature of the software being developed.

An Example Checklist for Java projects

I’d like to share a checklist below that I used for a project recently. I didn’t add my comments on the checklist items. The comments should be added to each item and if there are important details in the code, they should be added in the detailed report indicating the code blocks with the comments.

Clean Code & General

Use solution-problem domain names
Classes should be small
Functions should be small
Do one thing
Don’t repeat yourself (avoid duplication)—reusability
Explain yourself in your code
Use exceptions rather than return codes, nulls
Configurable

Security

Minimize the accessibility of classes and members
Avoid excessive logs for unusual behavior
Release resources (streams, connections, etc.) in all cases
Validate inputs
Validate outputs
Make public static fields final
Authorize and authenticate

Performance

Avoid excessive synchronization
Keep synchronized sections small
String concatenation
Avoid creating unnecessary objects

Extensibility

Make it easy to add enhancements with minimum changes
Components should easily be replaceable

Scalability

Consider large user base and data
Can be deployed in distributed systems

A few possible checklist item comments:

For naming checklist items, the below code piece complies with the conventions as it uses the solution domains as packaging name.

package com.google.search.common;

On the other hand, the following line would violate the Java package naming conventions since its letter capitalizations and domain usage are inconsistent.

package COM.google_search.common;

Sometimes a very long line of code could be used which usually violates the readability standards.
Or sometimes a variable used in a class scope in a concurrently run singleton Java object violates thread safety and could be a security issue.

Static Code Analysis

Reviewing is viewing the software by reviewer and the reviewers’ own comments and best practice notes will be used as the final output.

There are also static code analysis tools like PMD for Java which generally checks the code for bugs and clean code. This static code analysis, usually attached to the final code review report of the reviewer, is most helpful for an overview of the code.

Sometimes software development IDEs also provide best practices while writing the code. I like the PyCharm IDE’s smart clean code suggestions for Python, for example.

Automated Code Review

Automated testing is subject to measurable reports and static code analysis. Static code analysis tools can be scheduled for code checking and reporting.

Testing the code as a preparation for code review is another process that can be automated and already part of the SDLC processes. Some overlooked issues, like releasing resources and concurrency issues, can be also checked by automated tests and can be reported as automated code review results.

Conclusion

I have outlined the general code review cycle of a project.

Depending on the programming language and the architecture of the software to be developed there can be additional best practices like functional, non-functional, OOP design principles, etc.

Reviewers may extend or lessen their checklist items according to future plans, architecture or review request coverage.

Work philosophy canon

2018-05-07T00:00:00+00:00

Shared culture

Having some shared culture is important for working together well, and we can build that culture on familiar terminology, understanding, experiences, stories, and ideas.

To help give all of us at End Point some common reference points, we have collected a set of valuable articles and books that we encourage everyone to read.

Some of these have been standard reading at End Point for more than a decade, while others have been added over the years since we began doing this. Some are short and simple, others more in-depth. Our list is intentionally general, mostly avoiding specific technologies that only a subset of us use.

No one article or book can be entirely authoritative for all situations, but each gives us more of the wisdom out there to consider and judiciously apply where it fits.

Slow and steady

When new employees start at End Point, we ask them to read the articles during their first week or two, and the relevant books within roughly their first year.

Reading only a little at each sitting and spreading the reading out over time allows the ideas to sink in gradually and be incorporated into our work, rather than overwhelming with new information that cannot all be absorbed at once.

For everyone

Because we work in the software development industry, it is important that not only technical people such as developers, database experts, and system administrators be part of the shared culture. Everyone else at End Point including designers, project managers, sales, marketing, etc. should also be familiar with these articles and the terms and concepts they discuss:

Speed matters: Why working quickly is more important than it seems by James Somers
Please don’t just say hello in chat originally by Brandon High at nohello.com
Learn to Read the Source, Luke by Jeff Atwood—practical reasons free software and open source matter, and why actually using the source code matters
What is free software? by the Free Software Foundation and Richard Stallman
The Open Source Definition by the Open Source Initiative
Josh’s Rules (of Database Contracting) by Josh Berkus
On excellence by Ethan Rowe—about ownership, taking responsibility for the problem at hand
Conventions to know by Jon Jensen—little but important things that ease communication in our work
Selling Without Being Salesy by Jason Parks
Five Whys by Eric Ries (covered in more depth in his book The Lean Startup)
Software Is a Mess and I Feel Fine by Alan Stevens
Choose Boring Technology by Dan McKinley
Getting Real book by 37signals (now Basecamp)

For developers

These articles and books are targeted primarily at developers but enlightening for everyone:

A summary of the international standard date and time notation by Markus Kuhn
The Admin Zen by Michael Prokop—in true DevOps fashion, this system administration advice applies to development too
Things You Should Never Do, Part I by Joel Spolsky—don’t rewrite things from scratch (almost never, anyway)
On Git Commit Messages by Michael Jones; to get a feel for the long history of others sermonizing on the same worthwhile topic, see also:
- How to Write a Git Commit Message by Chris Beams
- On commit messages by Peter Hutterer
- A Note About Git Commit Messages by Tim Pope
Every line of code is always documented by Mislav Marohnić; see also The git pickaxe by Philip Potter
How to Read Other People’s Code—and Why by Christopher Schanck
You don’t know JavaScript by Michael Woloszynowicz—the lessons apply to most technologies
The Pragmatic Programmer book by Andy Hunt and Dave Thomas (see the write-up on the new 20th anniversary edition by Jon Jensen)
Practices of an Agile Developer book by Venkat Subramaniam and Andy Hunt—kind of a sequel to The Pragmatic Programmer (see the review by Ethan Rowe)

Any others?

We are always on the lookout for other readings that are helpful, so feel free to leave a comment with your favorites!

(Updated in early 2021 with articles on Git commit messages and history spelunking, and Choose Boring Technology.)

On excellence

2008-08-21T00:00:00+00:00

The interwebular collective cup runneth over with blog articles addressing the subject of what makes good software engineers good. It is a topic about which many opinions are expressed. What is less commonly addressed, however, is the possibility that the very qualities that make for good software engineers may also make for good technical leaders, good managers, and just good coworkers, period.

At End Point, we toss the term “ownership” around quite a lot, in a variety of contexts. When a particular task or responsibility goes from one person to another, we mention “ownership” when we need to communicate the significance and scope of the responsibility in question. The term may apply to a software engineering task, in which “owning” the problem means taking responsibility for all aspects of the engineering work, across the software stack, from prototyping to full development to deployment. It may also apply to a managerial or leadership role, for which “ownership” implies responsibility for all parties involved on a given project, task, or team, with the “soft” issues of human beings mattering at least as much—and probably more—as the “hard” issues of machines, software, etc.

Ultimately, ownership comes down to this: taking complete personal responsibility for all aspects of the problem at hand.

The owner does not wait helplessly for guidance from others; rather, the owner pushes things to a conclusion, and if guidance is truly necessary the owner pushes for it repeatedly until guidance is received. The owner does not put hard or potentially unpleasant things off, but instead embraces them and addresses them immediately. The owner does not limit him- or herself to a narrow comfort zone: he is not afraid to go to different parts of the software stack, she does not hesitate to call the business person to have difficult discussions about scope creep or design flaws or difficult tradeoff decisions. The owner never allows for the actions of others to serve as an excuse, and never regards any aspect of the task to be only somebody else’s problem. The owner treats the deliverable as a reflection of him- or herself. The owner looks objectively at the deliverable and does not shy away from criticism, instead embracing it for the learning opportunities that can come from reflection and analysis.

In other words, to act with ownership is to act as if all aspects of the project or duty are important and are the owner’s responsibility. That does not mean acting with ownership requires personally doing everything; owners can and should delegate as appropriate. But delegation does not mean that the responsibility is now somebody else’s problem: the owner engages in regular communication with the involved parties, and keeps the task or project in question on track. The owner understands that it still ultimately belongs to him or her. Furthermore, the owner recognizes ownership in others, appreciates it for what it is, expresses gratitude and respect for it, and does not feel threatened by it.

In our work, this kind of ownership is the root of excellence. The domain of ownership may vary wildly between individuals, but the degree of ownership exhibited directly correlates to the excellence the individual demonstrates within that domain. Ownership applies to everything, whether it means writing the most reliable, maintainable code possible, designing the most scalable systems, or ensuring that everybody on your team is productive and happy. If you are an owner, you understand this: there are no excuses, and it’s up to you. Furthermore, to make it happen, the owner also understands: at some point, the talking ends and the doing begins.

Ownership for a given problem may be granted to a particular individual. With a team of people, formal identification of a problem’s owner is necessary for operational clarity. However, such ownership is ultimately little more than a formality: true ownership can only be taken, and never granted. This model is at the heart of any meritocracy, and is true to the general principles of free software development.

Critically, ownership is part of an oral tradition, a cultural phenomenon. Ownership breeds excellence across teams. It spreads as people naturally admire it and emulate it when they encounter such excellence first-hand. It is never complete; no one individual with a full schedule will successfully display ownership across the board on all issues. We fall down sometimes. We overextend ourselves. We have to pick our battles. But part of ownership is recognizing mistakes so that we can do better.

It is my distinct pleasure to have witnessed such ownership, on numerous occasions. I’ve seen a coworker leap into system-wide problems—on systems this coworker ordinarily has little or nothing to do with—and not rest until every aspect of the system is in order and all members of the team involved with the support of that system understand exactly what it is that needed to be done. I’ve seen another tackle fiendishly difficult technical problems involving complex data modeling or hairy lock management in Postgres, pushing through all the roadblocks until success was achieved, no matter how challenging the problem and no matter how much investigation and mental gymnastics were required. Yet I’ve seen the same people show the same dedication and caring for work done on much smaller systems, on less interesting problems, in less dramatic scenarios. This is a small sampling from countless examples.

In my experience, the only proper response to such excellence is admiration, and it inspires a desire to emulate these fantastic coworkers to be similarly excellent and to earn their respect.

Again: it’s a cultural phenomenon. People do not learn this by reading books. Reading about it, and talking about it, are essential for understanding. Ultimately, though, doing is all that matters.

In the liner notes to his Live at the Blue Note box set, the great pianist Keith Jarrett thanks his illustrious colleagues (Jack DeJohnette and Gary Peacock) for reminding him that “the only standards worth having are the highest ones.” What more need be said?