• Where to find the team documentation?
  • Team practices documentation
  • Common vocabulary, terminology, glossary
  • User definition, use cases, requirements
  • Where is the documentation to build projects?
  • One step build process
  • Access to CI/CD
  • Access to git central repository
  • Access to slack
  • Installation of development tools/languages
  • Where to find the tasks being worked on?
  • Where to find the team roadmap?
  • Who prioritizes things?
  • Determine where I can have the biggest impact
  • Determine a timeline where I'll have reached my 80/20 at the company
  • What is the maturity of existing projects?
  • How fast can we iterate on certain aspects given the team/company composition?
  • Who are the core/principal/staff contributors?
  • What is the architecture of the system?
  • What is the database architecture?
  • Is the product a monolith or micro-services?
  • What (3rd party) tools are used?
  • List all the features you would like to develop
  • Define an appetite for the task (day, week, month, quarter)
  • Identify the features where the appetite differs between individuals and discuss them to reach consensus
  • Define the roles necessary to complete the task
  • Identify dependencies between features
  • Categorize the dependencies
    • Soft: somewhat depends on this other feature but isn't blocked by its absence from the codebase
    • Hard: depends on this other feature and is blocked by its absence from the codebase
  • Prioritize the features
  • Estimate the value of a features in dollars
  • Calculate a ROI (return on investment) as the estimated value of the feature divided by the defined appetite
  • Order tasks according to dependencies and ROI
08 Mar 2020

Reducing your error rate

History / Edit / PDF / EPUB / BIB / 3 min read (~481 words)

How can I reduce my error rate when using my skills?

When using skills in which you can make mistakes, it is important to monitor what you do and where you make your mistakes. Like any performance optimization problem, you want to figure out where you make the most mistakes and where you'll benefit the most from fixing those mistakes. If you make the same mistakes 100 times at the cost of a minute each time, that may be preferable to making 1 mistake that cost 100 minutes to fix, given that once the mistake happens, the cost stays the same.

Document your skills. Write down what you do, when you do it (triggers) and what kind errors you make during those steps. Evaluate how many times you make that mistake and how long it costs to fix. Then when you use your skills, track when you make mistakes and how long it takes you to fix the mistake.

As an example, think of a software engineer doing code reviews. Reviewing code requires going through a variety of checks: is the build passing? is the functionality properly implemented? are there tests? are the new files in the proper location? Without a list, the engineer is left looking at the code without any clear checklist. If he is methodical he will have a list he goes through in his head. If not, then he will most likely only look at the code and give it a summary opinion, that is, whether he likes what he sees, or not.

In both cases, given a non-explicit methodology, is it hard to assess where the mistakes are made and which mistakes cost the most to fix. If you don't check that tests were written for the new functionality or changes, what impact will it have in the future? Depending on how likely the code is to change, the likelihood that something gets broken may be significant. While adding a test may require a few minutes, one has to judge how much time would be wasted if a bug were introduced in the piece of code. As code complexity increases, so does the cost of fixing issues in that code.

With an explicit checklist you will be able to track the things that you want to verify before code is merged. As your checklist covers more and more case, this list will reduce the likelihood that the person who wrote code made a mistake that gets into production. By the same token it will increase your effectiveness as a software engineer to produce quality code.

05 Mar 2020

Adding tests to a project with no tests

History / Edit / PDF / EPUB / BIB / 2 min read (~394 words)

There are no tests on the project I joined. How do I get started?

When joining a new project without tests, here is the value you need to provide through the addition of tests:

  1. the application works and doesn't crash
  2. the application works and supports a few input cases
  3. the application works and supports a variety of input cases
  4. the application works and is robust to most input cases

Start by finding the main entrypoint of the program and call it in a test. Your test doesn't have to do much, other than ensuring you can start the program and possibly exit. Your goal should not be to assert anything yet, but to exert the code. Create a few tests that do very few things other than starting and terminating the program. Once you've covered a few use cases, you can use those tests to ensure that the application can start, do a few things, then terminate without crashing.

Start unit testing the various parts of the code that are critical. To determine what is critical, you'll have to dig into the code. With the tests you initially wrote you will get a sense of the "critical" pieces, simply due to the fact that they are executed whenever the program starts and stops, which are two things you always want to work.

When writing unit tests, always aim to write a test case that covers the happy path first. You want to demonstrate that the functionality a class or function is supposed to provide is there first and foremost. Then you want to test its robustness and its ability to handle a variety of input cases. Given a large codebase, start by covering most of the code with the happy paths before you start to dig into the special cases.

03 Mar 2020

Useful code refactoring

History / Edit / PDF / EPUB / BIB / 2 min read (~251 words)

How can you tell between noisy and useful code refactoring?

The classical adage in software development is that "if it ain't broke, don't fix it". Code may not be in an ideal state, but you should not focus on refactoring it if you aren't working to change it to do something else or so that it can be used in other parts of the code. It is fine to do code refactoring from time to time, especially if you have free cycles and know about a few pieces of code that have been bothersome. However, spending time refactoring systems that are already working but a bit clunky may not be the best use of time, especially if you or your team don't have free cycles to spare to review your changes. A better use of time may for example to help others on their tasks or to prepare future work so it goes smoothly.

In a business environment, a refactor also means implicating other developers to review your changes. As such, this introduces distractions in those developers that could be more focused.

In this case, whether a refactor or other changes to the code is noisy is a matter of timing.