Readable Code

Readable code means that the code has a good balance of being easy to understand in terms of what it is doing, and of being concise.

Why does readable code matter?

When code is easy to read, it’s easy to debug, maintain, and extend. 

It’s not uncommon for a developer to write code at the beginning of a system development process, and then realize a year later that they don’t understand their own code and thus will need to re-teach themselves their own system. 

If someone else wrote the code, and it’s unreadable, it’s not uncommon for developers to re-write the entire system as a result, which is an inefficient way to build software.


Structure Your Code

Classes and methods should be consistent, easy to understand, and easy to navigate.

Simplify Your Code

Aim to make your code elegant—simple to read, orderly, and easy to understand. Don’t try to over-complicate things with elaborate tricks. Keep your classes a reasonable size and most of your functions short. 

Stick To The Style Guide

If the repository you’re working in has standard code formatting and style guidelines, use them. Stick to the maximum length per line used in other code in that repository, etc.

Names Should Be Self-Explanatory

A big aspect of making your code easy to read lies in the names you choose. The names of your functions should clearly describe their purpose. Name your variables, function, and methods in a way that describes what they do or what they are. 

For example, if your variable gets something, consider including “get” in its name. If you can’t name the method or function without using many words, the function may be too complicated. Consider going back and breaking complicated functions into smaller functions to simplify.

Ensure Blocks Are Self-Contained

The single responsibility principle means that every building block does only one thing. All building blocks, including methods, variables, and classes, follow this rule so it’s easy for the person reading the code to understand their responsibility. 

When your code follows this principle, it’s easier to maintain and more scalable. When concerns are separated, you can focus on what features you actually want to work on rather than having to navigate interconnected lines of code.

Ensure Comments Are Minimal

Comments shouldn’t tell us what we already know. They should tell us why things are happening. You shouldn’t have to write more than 1-2 lines in a comment to explain what the code is doing. If you have to, consider rewriting the code until it is more readable. If the code is obvious, avoid comments altogether. The code should be able to speak for itself in many cases. 


How to Review a PR (Pull Request)

This post is about reviewing Pull Requests (PRs) on a software engineering team, often submitted in a source code system like Github. It’s meant to be a concise guide.

Goals of a PR Review

  • Catch issues in the code that the submitter may have missed
  • Offer advice in making the code submission better
  • Complete any team-specific PR review required steps

For many PRs, you don’t need to be an expert in the stack or programming language that is used in the PR. 

The time it takes to review a PR is directly related to how long the PR took to create and how many changes it includes. You should expect to spend more time reviewing a large PR than a small PR.

Required Steps When Reviewing

The steps below apply to PRs with changes to code. If it’s a non-code PR (e.g. a wiki update), the reviewer should just check for typos and that the changes make sense to them.

  1. Confirm that the PR description contains at least 1-2 items describing the changes being made and the reason for those changes.
  2. If there aren’t automated tests, confirm that the PR description contains at least 1-2 items describing how the changes were tested.
  3. Check each changed file for potential bugs that the submitter may have missed.
  4. Check to see if the code is readable.
  5. Check for typos in the comments and readmes.
  6. If you’re not proficient with the programming language or framework used, make a note of that in your review.
    1. For example, “I’m a beginner when it comes to JavaScript. This PR looks good to me, but if you have any doubts about your code or would like a more in-depth review, please consider requesting a second review in ___ channel.”
    2. You don’t have to be an expert in the system which the PR is changing, but you should have a basic understanding of what’s going on. If you have absolutely no clue, it’s best to either loop in someone who does, suggest that the submitter bump their request for a review, or ask for a review in another channel. 
  1. If there are any parts that are particularly difficult to understand, consider suggesting that the submitter refactor or add a comment.


🎉 Lgtm!

My gitlab CI configuration experience level: beginner.

I did not see any obvious errors, everything looks readable and elegant.

If at all possible, try to make future PRs smaller. If not possible, please note that in the PR description.

  • If many files are being renamed, I suggest making a separate PR just for the renaming.
  • There were also formatting/lint updates in this PR. In the future, I suggest a separate PR or including automatic changes like that in a separate renaming PR.


  • Is it possible to move the configuration constants (e.g. ROLE_PREFIX) to a config file or AWS systems manager? If yes, no need to change this PR, but please consider for a future PR.

It looks like there are some major changes to the gitlab pipeline in this PR. I reviewed the testing methodology, and it looks pretty good, but due to the size of this PR, please take a second look at the tests you did to make sure these changes wont break anything before merging the PR.

Great work 🔥. Thank you for making these gitlab CI improvements!

Set up L2TP/IPSec PSK on Surface RT

Surface RT stock imageAt this time, Microsoft’s Surface RT has a very limited GUI for editing VPN parameters. For example, there’s no input field for a pre-shared key commonly used with L2TP/IPSec VPN type. Since there’s limited information for setting up more advanced VPN connections on Surface RT, I figured I would post these simple steps.

  1. Use Windows 8 powershell vpn cmdlet:
  2. Open up Powershell
  3. Example:Add-VpnConnection –Name “My VPN” –ServerAddress –TunnelType L2tp –L2tpPsk 5E2BBC9D423B50A2 –RememberCredential 1 –SplitTunneling 1

S Symbol in Your Emails

I recently ran into an issue where the š character appeared in a client’s emails that weren’t there when she sent them. This was apparently caused by Outlook 2011’s autoformatting options that replaced … with a special ellipses character, which wasn’t supported in all mail clients.

Here’s how you can disable that feature and thus avoid unintentional symbols in your emails.

1. Open Outlook and go to Outlook preferences.

Screen Shot 2013-11-06 at 10.41.31 AM

2. Select AutoCorrect under the Personal Settings category.

3. Select AutoFormat tab and uncheck “…” with ellipses.

Screen Shot 2013-11-06 at 10.43.42 AM

Pesky RunDLL Virus Errors at Logon

One of our user’s computers was infected with a virus that, after being removed and cleaned up, left these annoying RunDLL errors for DLL files with randomly generated filenames which occurred every time the user would login:

logon errors

I didn’t get far trying to google some keywords related to the errors. However, some results did point me in the right direction for resolving the issue.

Basically, you want to check every possible repository of startup items or commands. In the registry, most google results told me to check the following locations.

  • HKEY_LOCAL_MACHINE/SOFTWARE/Microsoft/Windows/CurrentVersion/Run
  • HKEY_CURRENT_USER/SOFTWARE/Microsoft/Windows/CurrentVersion/Run

However, where these virus-caused items actually ended up being was under a specific user profile in HKEY_USERS:


I should mention that CCleaner did not list them under the startup category and neither did msconfig, so registry might be the only way to find them that I know of.

Office 365 SMTP Settings

Update, in new office 365 UI:

Server name:
Port: 587
Encryption method: TLS

  1. Login in to the Microsoft Online Services Portal.
  2. Click on Outlook.
  3. Click on the question mark icon in the upper right corner of the page.
  4. Click on About.
  5. There will be a section titled External SMTP setting that will contain the server name, encryption type and port. You will be able to use those along with your username and password to send email from devices/programs.


Change Office 365 Password Expiration Period

Update: This is now available via the Office 365 administration portal:

Screen Shot 2013-10-11 at 10.03.26 AM

If 90 days seems too short of a period before your Office 365 users’ passwords expire, you can change it via a powershell cmdlet.

Set-MsolPasswordPolicy -ValidityPeriod <days> -NotificationDays <days> -DomainName

Validity Period: time before expiration

Notification Days: how many days prior to expiration that the user begins to receive notification pop-up

Make sure you use Powershell to connect to MS online service first: