On Self Documenting Code

Comments in code is a heavily discussed topic within the software world. This is partly because it is frowned upon by phrases like

Good code should be self documenting

Good code should indeed be self documenting but to a certain level. Whenever I’m working on a project for the first time there will always be certain decisions made because they were the best fit for that project. Comments can indicate the thought process behind this and help you understand the program flow.

The thing that we all agree upon is that variables and function names should be a clear indication of what they contain. The goal is to create consistent and well thought out code.

const data = manager.getAll(true);

const x = data.map((i) => i.email);

vs

const newsletterSubscribers = subscriberManager.getAllSubscribers({
    active: true,
});

const emailAddresses = newsletterSubscribers.map(
    (subscriber) => subscriber.email
);

Let me know which one you prefer!