Bus factor - is a minimum number of key people that have to disappear before the project collapses. This idea highlights an important question: Are you truly working as a team, or is your project in sharp decline due to over-reliance on very specific individuals?

Of course, there is no need for all team members to equally know everything or being absolutely replaceable at any time. And, at the same time, do people feel confident to go on vacation? To take a sick day? Delegate code review at busy times? Trust others to represent the team on some meeting?

Do you have documentation people can use in case of absence of the key person? Playbooks? Do they frequently share and explain their technical decisions and vision? Do you have an architect who is not very good at written or verbal communications and is not capable of explaining the "why" behind their requests?

Do you have a person who is really proud they've built the entire system? All by themselves! And even more proud to single-handedly and heroically support it on Sunday morning? What happens to the project and the managers when that person goes on vacation? Do they grab the laptop w/ them because they think that no one is capable of handling anything?

How good is your manager? What would happen if they go on vacation? Change the job? How do you onboard new teammates? DO you board new teammates or just throw them at the code?

What happens when the code owner is unavailable for a day or two? Are the people blocked? Can they be unblocked? What if it is a 3-week vacation?

When a single point of knowledge has a bus factor of less than 2 you might find the team in a very peculiar situation. Not only it can lead to a disaster when the person is unavailable, but it can also drastically reduce the productivity of your team in the long term.

What can you do?

• Accept people's opinions. Not everybody is the same. Having alternative perspectives is a strength and the power of working as a team.

• Make quality code reviews your team habit - both genuinely asking for people's opinion and providing clear explanations of your feedback to them.

• Documentation - Write things down, ask for review, and own it.

• Pair program - The forum where questions can find answers in their depths and as early as possible.

• Delegate - Can't? Why not? Don't you trust your teammates to handle the situation?

• Navigate - Don't know the answer? Do you know someone else who DOES know the answer?

• Simplify - is your code and documentation easy to read and accessible to everyone?

• Explain your decisions - Explain the "why" behind your choices to help others understand your point of view and learn from your thought process.

• Teach and Learn - don't let people miss out on the learning opportunities even if it slows things down in the short term.

Share the knowledge, encourage solving unknowns, and foster collaboration! Be a good teammate and a good person.

Further reading: Bus Factor on Wikipedia.

This is a conversation space exclusively for subscribers—kind of like a group chat or live hangout. I’ll post questions and updates that come my way, and you can jump into the discussion.

Join chat

How to get started

1. Get the Substack app by clicking this link or the button below. New chat threads won’t be sent sent via email, so turn on push notifications so you don’t miss conversation as it happens. You can also access chat on the web.

Get app

2. Open the app and tap the Chat icon. It looks like two bubbles in the bottom bar, and you’ll see a row for my chat inside.

3. That’s it! Jump into my thread to say hi, and if you have any issues, check out Substack’s FAQ.

Iteration in Pre-C++11

Before C++11, there were few common ways to iterate over a collection (std::vector specifically). One of them is to use C++'s iterators:

for (
  std::vector<Employee>::const_iterator it = begin(input);
  it != end(input);
  it++
) {
  if (it->job == "programmer")
    names.push_back(it->name);
}

The iterators provide a unified (unified is a buzzword recently) way to traverse over all types of collections. In C++, iterators are zero-cost abstraction, meaning developers incur (almost?) no performance overhead when using them. However, despite their universality, simply using indices can make the code more concise, since the type of the iterator is quite cumbersome to type:

for (int ii = 0; ii < input.size(); ++ii) {
  const Employee& element = input[ii];

  if (element.job == "programmer")
    names.push_back(element.name);
}

Note: Using double "i" is an old-school way of defining an "i", which is very easy to search for in any text editor.

C++11 is like a new language!

In C++11, we've got so many improvements, that it feels almost like a new language.

With introduction of auto, one can simply avoid writing the iterator type:

for (auto it = begin(input); it != end(input); it++) {
  if (it->job == "programmer")
    names.push_back(it->name);
}

Yes, the only difference is std::vector<Employee>::const_iterator was replaced with auto. Despite the not-quite-trivial type deduction rules, auto is very good default option for very verbose names.

Also, C++11 brings range-based for loops, what makes the life so much easier:

for (const auto& element: input) {
  if (element.job == "programmer")
    names.push_back(element.name);
}

Bottom Line

The range-base for loop is an alternative syntax for the iterator-based approach and requires the collection to be "iterable", i.e. implement speicific properties of a collection and iterator types.

The range-based for loop is implemented using C++'s iterators. The iterators are implemented using concrete types without extra overhead. The iterator implementation as efficient as the low-level code. The range-based for loop is a perfect example of zero-cost abstraction. Also, each of the ways of iterating over a collection would likely lead to nearly identical assembly code. And each way still works on newest compilers!

Something went wrong, please try again later.

If the error doesn't go away, what might be very frustrating on its own, the user have to call the support… All of us know, how daunting the experience could be. And even after the long waiting, the support team would do the troubleshooting and then… the support would suggest to reinstall your Operating System or return\replace the device.

Not all people equally know and care about how the "bits and bytes" work. And for many of the people, such error message luckily might mean the error will be fixed… somehow… on its own…

Also, one might see error messages like this:

• "Failed make an RPC request to "http://backend.example.com (Status Code: 500)".

• "Failed to parse JSON message on line 347".

• "Server returns \r\r where \r\n is expected".

That kind of error message also do not bring much value even to skilled software engineer. Because complexity of the system might be to high to quickly jump into the right conclusion.

And, it seems like we're loosing some value there… and what does it have to do with context in error messages?! What does the error message lack of is the context!

Consider the following Python function which is supposed to fetch user information basing on user id and the given HTTP client:

def show_user_name(session):
    try:
        user_name = fetch_user_name(session.client, session.user_id)
        show('User Name: {}'.format(user_name))
    except Exception:
        show('Error: Something went wrong, please try again later.')

The possible outcome of the function is to print either the user name or an error message w/o any extra information on kind of error we have. The current solution's built in a such way, that it's hard to add any meaningful information which comes from fetch_user_name function. But, we still can improve the side:

logger = logging.getLogger(__name__)

def show_user_name(session):
    try:
        user_name = fetch_user_name(session.client, session.user_id)
        show('User Name: {}'.format(user_name))
    except Exception as e:
        logger.exception(
            'while fetching user name for user id {}.'.format(session.user_id)
        )

        show('Error: {} while fetching user name for {}'.format(repr(e)), user_id)

As you can see, we added few statements here and there and here're the improvements:

• The error message contains the information about the user id and what kind of exception is occurring during fetching the information. In case developers receive a ticket, they already have much more context to address the problem quicker w/ fewer turn-arounds.

• The logger statement adds very useful context information for developers… Stacktrace! Which on its own might contain a lot more, but might be less useful to the end users.

• Logging provides useful tool for developers to proactively solve the problems and not to wait for the user feedback or support ticket. Because the errors can be addressed earlier, the cost of software development is lower.

Now, let's take a look into the function implementation.

def fetch_user_name(client, user_id):
    response = client.request(
        "/api/user/{}".format(user_id)
    )

    serialized_response = json.loads(response)

    return serialized_response['preferred_name']

From the first sight, there nothing bad. But, does it give enough information about the error? It is hard to say:

• What kind of exceptions does client.request raises?

• What do we do in case of failed JSON parsing?

• What if the field is not present in the response?

The code might be doing an absolutely correct and expected thing (take a look into the unit-tests of the function to make sure), but there might be also an alternative view:

def fetch_user_name(client, user_id):
    try:
        response = client.request(
            "/api/user/{}".format(user_id)
        )
    except http_client.Error as e:
        raise Error(
            'Failed to fetch user info for client {} and user id {}.'.format(
                repr(client), repr(user_id)
            )
        ) from e

    try:
        serialized_response = json.loads(response)
    except json.JSONDecodeError as e:
        raise Error(
            'Failed to parse JSON response: {}, for client {}, user id {}'.format(
                repr(response),
                repr(client),
                repr(user_id)
            )
        ) from e

    try:
        return serialized_response['preferred_name']
    except KeyError as e:
        raise Error(
            """
            Failed to retrieve 'preferred_name' from the response.
            Available Keys {}.
            Response: {}.
            User id: {}.
            """.format(
                serialized_response.keys(),
                repr(response),
                repr(user_id)
            )
        ) from e

Now, developers and clients have much more available information stored in the context:

• from e allows Python to "chain" exceptions and keeps stacktrace history. When such exception is logged, there is all information on the original exception. See Python Docs.

• Each of the handler is explicit and gives a clue that those situations might happen an developers know about them, just because they explicitly handle them.

• The information, given to the function, is stored in the error message, what make understanding of the issue easier.

The result function is a great improvement on providing context, but has a couple problems:

• Function body is longer: Seems like not a big issue, taking into account the cognitive load is about the same.

• Duplicates of the information on call-site and function. In case, you own both you can always eliminate the duplicate, but when you don't know, it's better to log more than less?

• The function "records" the same information multiple times.

Some of the problems can be addressed knowing enough information about who and how uses the function. As an example:

def fetch_user_name(client, user_id):
    try:
        return _fetch_user_name_internal(client, user_id)
    except Error as e:
        raise Error(
            '{} while fetching user name for user id {} and client {}.'.format(
                repr(e),
                repr(user_id),
                repr(client)
            )
        ) from e

def _fetch_user_name_internal(client, user_id):
    try:
        response = client.request(
            "/api/user/{}".format(user_id)
        )
    except http_client.Error as e:
        raise Error(
            '{} while making api call to /api/user/<user_id>'.format(repr(e))
        ) from e

    try:
        serialized_response = json.loads(response)
    except json.JSONDecodeError as e:
        raise Error(
            '{} while serializing response {} into JSON'.format(repr(e), response)
        ) from e

    try:
        return serialized_response['preferred_name']
    except KeyError as e:
        raise Error(
            '{} while getting "preferred_name" from response: {}'.format(
                repr(e),
                repr(response)
            )
        )

Now we have fewer duplicates of the information and the functions are smaller.

As a results of the improvements we have much more information in case of errors. User has something to act on or to share w/ the support and developers can easier find the information in the logs and even proactively fix the errors for some users.

Naming is one of Two Hard Things.

How would one name an interface in C++?

Very frequent pattern is to add a suffix to an interface name like this:

class PaymentServiceInterface {
public:
  virtual ~PaymentServiceInterface() = default;

  virtual void Pay(int employee_id) = 0;
};

One of the perspective on this is, the name is excessive since from declaration anybody can see that the class is an interface since it has no fields, and contains only pure virtual member function declaration. The most frequent argument for such kind of naming is the client side make the fact invisible and prefix interface is more readable from the client code:

void example1(PaymentServiceInterface& payment_service) { ... }

void example2(PaymentServiceInterface* payment_service) { ... }

void example3(std::unique_ptr<PaymentServiceInterface> payment_service) { ... }

As anybody clearly can see the name reflect the fact the class is an interface and should be treated as such. But, what does it mean for us? How do we have to treat the interface? Why should it be any different from any other classes?

There is nothing special about such class, it is pure abstract class and we can't make a copy of it or move it simply because we can't declare a variable of the abstract class (a.k.a. interface).

Hold on, but the client side clearly shows: All calls to the interface are polymorphic and without suffix "interface" readers wouldn't be able to understand it and that's absolutely correct:

void example4(PaymentServiceInterface& payment_service) {
  constexpr int kKentBeckEmployeeId = 1
  payment_service.Pay(/*employee_id=*/kKentBeckEmployeeId);
}

But, is it important? I think, this is a place where naming became very important. Let's consider some practical examples of names which might be a value?

• "ID" - sounds like a great wrapper for some value type with likely utility functions and invariant validations.

• "string" - we all know the what the string is and it is clearly a value type.

• "Options" - Would you expect to see a shared pointer to a polymorphic class in such place? I hope, not. But, things happen. Bad things.

On the other hand, we can consider the following my-guts-say-it-is-abstract kind of names:

• "Service" - whether it's a network service, or client to some database, or maybe some in-process implementation of some long-running job, I am very confident, it's something abstract.

• "Repository" - I don't want my class to be copied a bunch of time in such case, and I defiantly want to have some stub implementation for testing.

• "Delegate" - Clearly abstract reference type.

So, when naming can give us a good hint about how to use a specific class, wouldn't it still make sense to keep "interface" prefix? It is up to you to make this decision, but here are my 2 cents on why it shouldn't be the case.

• After sometime of using interfaces, people tend to ignore the prefix "interface" and it became more annoying clutter which only states very obvious things. Do the people use that interface suffix in their vocabulary ever? "Now, we are passing Extension Service Interface into this function.", Likely, the word "Interface" became redundant.

• The client code spells the interface name more frequently, just because we design the systems around the abstraction and do not declare an abstraction to just ignore it later. Extra clutter to express obvious thing.

Consider the following example:

class PaymentService {
public:
  virtual ~PaymentService() = default;

  virtual void Pay(int employee_id) = 0;
};

The interface doesn't have "interface" suffix and the name clearly states abstract behavior. Now, let's consider some client code:

class PaymentScheduler {
public:
  explicit PaymentScheduler(
    std::unique_ptr<PaymentService> payment_service,
    std::unique_ptr<EmployeeRepository> employee_repository):
    payment_service_(ABSL_DIE_IF_NULL(payment_service)),
    employee_repository_(ABSL_DIE_IF_NULL(employee_repository)) {}

  void Execute() {
    // ...
  }

private:
  std::unique_ptr<PaymentService> payment_service_;
  std::unique_ptr<EmployeeRepository> employee_repository_;
}

and here's another version where all of the abstractions are suffixed with word "interface":

class PaymentScheduler {
public:
  explicit PaymentScheduler(
    std::unique_ptr<PaymentServiceInterface> payment_service,
    std::unique_ptr<EmployeeRepositoryInterface> employee_repository):
    payment_service_(ABSL_DIE_IF_NULL(payment_service)),
    employee_repository_(ABSL_DIE_IF_NULL(employee_repository)) {}

  void Execute() {
    // ...
  }

private:
  std::unique_ptr<PaymentServiceInterface> payment_service_;
  std::unique_ptr<EmployeeRepositoryInterface> employee_repository_;
}

And when you successful application grows, the number of abstractions and layers where those abstractions have to pass through grows as well. And the only thin the suffix adds is a clutter.

What are the other properties of a good interface would you define?

As simple as this:

class PaymentService {
public:
  virtual ~PaymentService() = default;

  virtual void Pay(int employee_id) = 0;
};

When interface has non-virtual destructor, derived (sub-) classes do not have clear way to release their resources and hence should be avoided. If someone defines an interface without virtual destructor, it is clearly a bug.

• virtual tells the user: "The class is designed for inheritance".

• default describes the intention better than default implementation, saying "We don't plant to do anything tricky here."

Also, The derived classes still keep have their move and copy operations despite the base class (interface) has a user-declared destructor and hence doesn't have implicitly declared/defined move operations (See Implicitly-declared move constructor). In order to test it, one can do the following:

class PaymentService {
public:
  virtual ~PaymentService() = default;
};

class DerivedService: public PaymentService {
    public:
    std::string value = "value";
};

template <typename T>
void Consume(T&& value) {
    T unusedTmp = std::forward<T>(value);
}

int main() {
    auto derivedService = DerivedService();
    std::cout << "Value before consume: \"" 
              << derivedService.value << '"' << '\n';
    Consume(std::move(derivedService));
    std::cout << "Value after consume: \"" 
              << derivedService.value << '"' << '\n';

    return 0;
}

The output is

Value before consume: "value"
Value after consume: ""

As expected, the field of DerivedService was moved and has the string has empty (moved-out) state.

Alternative: Declare everything final.

Keyword final didn't exist prior C++11 (final specifier) and there was no simple way to define a class which is not designed to be inherited from. Many C++ developers adopted a rule which says "Do not inherit from a class which doesn't have virtual destructor". And it make sense, because sub-classes don't have a reasonable way to release their resources.

In some other placer, developers adopts even stricter rule "Do not inherit from a class which is not designed to be inherited from", which is, in most cases, stated by documentation. Such rule is easy to use because most of the classes are not designed to be inherited from.

But, what about final (post-C++11)? Unfortunately final has its own problems. As an example, final makes the code to rigid to refactoring. If someone decides temporarily inherit from our class in order to provide a stub for the new implementation, they wouldn't be able. And they would have to fix the class to be non-final first. Which might break some other assumptions about the code.

Here's an example of unexpected behavior.

class PaymentService {
public:
  virtual ~PaymentService() = default;

  explicit PaymentService(
    std::string ip, int port): ip_(ip), port_(port) {}

  virtual void DoSomething() const = 0;

  std::string ip_;
  int port_;
};

The PaymentService has 2 fields: ip_ and port, hence the constructor and assignment operation of the class do actual work of copying the data from one instance to another. The same for move-semantics. Here's an example of an implementation:

class RelayPaymentService: public PaymentService {
public:
  explicit RelayPaymentService(
    std::string ip, int port, std::string relay
  ): PaymentService(ip, port), relay_(relay) {}

  void DoSomething() const override {
    // some code here...
  }

  std::string relay_;
};

and second

class ProxyPaymentService: public PaymentService {
public:
  explicit ProxyPaymentService(
    std::string ip, int port, std::string proxy
  ): PaymentService(ip, port), proxy_(proxy) {}

  void DoSomething() const override {
    // some code here...
  }

  std::string proxy_;
};

The implementation has an extra-field relay_. Notice, all fields are public for educational purpose and shouldn't be exposed by default. Now, let's define a possible use-case where an instance might be sliced, but it is hard to notice:

void assignPaymentService(PaymentService& one, PaymentService& two) {
    one = two;
}

Simply assigning an reference of one instance to another cause here some troubles. Here's an example of code running the above-mentioned code:

std::cout << "Running example1...\n";

std::unique_ptr<RelayPaymentService> relay_payment_service =
  std::make_unique<RelayPaymentService>(
    "127.0.0.1",
    8080,
    "<relay>"
  );

std::unique_ptr<ProxyPaymentService> proxy_payment_service =
  std::make_unique<ProxyPaymentService>(
    "192.168.1.12",
    8081,
    "<proxy>"
  );

assignPaymentService(*relay_payment_service, *proxy_payment_service);

std::cout << "ip: " << relay_payment_service->ip_ << ",\n"
          << "port: " << relay_payment_service->port_ << ",\n"
          << "relay: " << relay_payment_service->relay_ << ",\n";

Now we have multiple possible outcomes:

• The code doesn't compile since we try to assign 2 different types

• ip_ and port_ are not changed since we try to assign 2 different types

• relay_ value would turn to proxy_ value which is "<proxy>".

None of the things, actually, happen:

• The code compiles successfully

• The values of ip_ and port_ are updated

• relay_ stays "<relay>" and proxy_ stays "<proxy>".

The outcome is not expected, the types of relay_payment_service and proxy_payment_service stay the same. Where in the most reference-based languages the underlying reference would be changed. In order to prevent such partial data exchange, it is good to avoid any fields in classes which are supposed to be used as interfaces.

Here's an example how to define a good interface:

struct LoginSession {
  int last_time_active;
};

class Account {
public:
  virtual ~Account() = default;

  virtual std::vector<LoginSession> FetchLoginSessions(
    int since) const = 0;
};

The interface has the following properties:

• does NOT declare any fields

• defines default virtual destructor

• does NOT contain any user-defined implementations

• does NOT use interface in its name

Let's figure out each point one-by-one (to be continued…)

Remark, Emacs has build-in packages distributed within Emacs. Frequently, those package have the other version which can be installed using various packages sources. In the most of the cases, those are the same packages, but coming from different update channels (Emacs distribution vs. package repository). Once some packages became widely and frequently used, they might be integrated into Emacs distribution by Emacs maintainers. Some of the examples are Eglot, Tree-Sitter, use-package.

Fortunately, as Magit message suggests, there is a way to solve it. Emacs has a flag which overrides the behavior and allow to install/upgrade a package from using external sources (package repository):

(setq package-install-upgrade-built-in 't)

But, unfortunately, not all commands respect the flag. Documentation of package-upgrade-all command says:

Currently, packages which are part of the Emacs distribution are not upgraded by this command. To enable upgrading such a package using this command, first upgrade the package to a newer version from ELPA by using ‘i’ after ‘M-x list-packages’.

But, there is a solution: One can navigate to the list of package using package-list-packages command, press U, and then x in order to upgrade all the package and transit them from "build-in" to "external" state. From that point, all of the packages can be updated using package-upgrade-all.

I used to be a single-file-per-declaration guy… And in a case when I had a more than once class or structure per single entry of API, I tend to define multiple files for each possible declaration:

~/project/ImageReader/
  ImageReaderError.swift
  ImageReader.swift
  Image.swift
  ...

And I do not see too many problems with that. I just combine logic into a single folder and keep the files together. So, once I need to change the API, I change some of those files. There is a way to improve it, but it's a bit later… The other case I frequently see is structuring the project by grouping declarations by their type. For example,

~/project/errors/
  ImageReaderError.swift
  CameraError.swift
  ...
~/project/
  ImageReader.swift
  Camera.swift
  ...

This is quite similar what one can see in the new web framework for cool kids people use where they combine controllers, errors, models separately. What's the matter with that? Low cohesion… I need to introduce a single change in some functionality the code lays in absolutely random places. Having large projects structured this way makes it hard for new people to discover the possible scenarios, and make API documentation harder.

When the code for image reading is in the same place, I can see what is going on and why, where having errors and/or models in a separate, predefined structure makes it hard to find. Of course, after a while of working on a project anybody can get used to it and stop seeing problem in that. And when new people come to project, listen! And listen hard! If they find it hard, it is hard, but you do not notice (or choose to ignore?).

Now, let's consider a better option (from my point, of course): I have the only file: ~project/ImageReader.swift which is self-contained and has necessary documentation (I'd like to avoid it as much as I can, or minimize):

struct ImageReader {
  init(from directory: String) { ... }

  struct Error: `Swift`.Error {
    var message: String
  }

  func read(filename: String) throws -> Image { ... }
}

In my opinion, it is clear from the definition what kind of error the image reader can produce. Of course, it doesn't say if it can produce anything else and we probably can document it, but I would expect it to produce nothing but ImageReader.Error until something else is stated.

Now the logic which changes together stays in the same place. One might ask: Why you have only error message and do not have a bunch of error codes in the error definition? Well, nobody ever asked me to do so. When the API (the ImageReader) is project internal code and is not a part of some library, I do not expose any error which can be handled outside, until anybody needs to handle them.

Having separate code for each possible scenario is leading to the over-engineering. I know you think it should be perfect, I've been there. But it actually shouldn't. We are better to be ready for a change rather than defining perfect API which is never going to see the light. Additionally, we need to know how the API is going to be used (oh no, this is not perfect). Yes, it is not and it should not be. In the most of cases, we define an API and we (the project developers) are users of that API.

One of the possible examples might be: The image reader is used only for reading application asserts (resources) delivered inside of an application. In such a case, the error should never (theoretically) happen and we can't even test for it. But, I would still provide reasonable readable error with as much context as possible in case when it happens . Just because I do not wanna ask users to collect their logs and ask a bunch of questions in order to reproduce the error. I wanna be able to see the error message, add test, fix the bug, and provide value. I also wanna be friendly to my colleagues and provide them as much details as possible when they make a mistake, or type, or forget to add a file to the resources.

An alternative would be to have this:

struct ImageReader {
  init(from directory: String) { ... }

  // See `ImageReaderError.swift` for error details.
  func read(filename: String) throws -> Image { ... }
}

Now, the code is less cohesive and I need to look in a separate file to understand the possible errors (or read the code of course). Modern IDEs can make it relatively easy task, but would it be more readable? Would it be easier to spot a type, mistake, some inconsistency when the errors are defined in a separate file? Would it make code-review easier/faster? Of course, I can always split the screen and open errors in a separate file and make my life somehow better. And in some cases, that what I have to do.

The errors are the part of the API and should be documented as well. Having errors makes it easier to review, refactor the code, spot mistakes and simply to self-document the code. Someone might see value in having all errors in a single place, but somehow such cases happen very rarely…

Extra note: When the class grows and you'd like to break it down into multiple files, but support the same API you always have multiple options:

• Keep everything as it is and let the module grow

• Break it down into multiple sub-classes (maybe even private): with their own errors

• Break down only implementation, but keep external API the same and re-use the same error

The last one would require you to extract error into a separate file and make your internal implementations depend on it:

~/project/ImageReader/...
  Error.swift
  ImageReader.swift
  InternalPNGReader.swift
  InternalJPEGReader.swift
  InternalOpenFile.swift

Each of Internal depends on the Error.swift and ImageReader.swift depends eon each of Internal*. This is of course a trade of and there is more than one way to solve that. And you're the one who knows the most!