DEV Community: Tom Collins

Invest time into writing questions: Tips for writing better questions

Tom Collins — Mon, 19 Jul 2021 12:11:58 +0000

The essence of writing code is problem solving. This problem solving will often be a solitary task, you, the keyboard and a code editor. Not all problems are easily solved in this vacuum. For many problems we will benefit from the help of others.

Every problem or task when writing code is a chance to learn from others. A complex task can usually benefit from the input of multiple developers.

The more effort we put into asking a question, the more likely we will get an appropriate answer. When posing a question, whether this be over slack, email or in person, we should think of the time put into asking this question as an investment. A poorly framed question with little context will likely yield low quality answers, if any at all. A well structured question that describes the problem in full is far more likely to be answered well. With that, let's look at how we can ask better questions.

Asking good questions is all about context. We should frame the question with as much information as we can. When asking online you will likely need to give more context that when asking within a team. The same rules generally apply to either scenario though.

1. Include information on the environment

A key piece of information will always be where this software is running. Is this a performance issue in production? Is this on your local machine? Documentation should be provided with any steps required to set up the environment.

2. Your issue should be reproducible

If there are some UI steps required to reproduce a bug, be specific about these. Include the branch name if relevant. Always have your code pushed to a remote repo.

If you are asking online (stack overflow), create a reproducible code sample on Codepen, Code Sandbox or some other publicly available sandbox.

3. Include errors

Don't stop at describing the issue. Include any stack traces from logs or console output. Check the network tab for any related network errors and include anything that is relevant

4. List the steps you have taken

Give information on what you have already tried. What commands did you run? What code did you change? What debugging did you do? This will help frame the question and narrow the focus by eliminating these steps.

5. Link to code

When the question is on a specific piece of code, link to this in github or give a file path and line number. Don't just give a function name. Help other developers find the code you are referring to.

6. Explain the problem in full

For more general questions on what technology or a library to use, explain what you are trying to achieve. List the things that matter as well as what matters less. Include any constraints you may have.

In summary:

Ensure you give enough information so that the same state can be reached in the application
Add as much context as you can

How do you manage wellness and avoid distractions?

Tom Collins — Sat, 02 May 2020 18:05:06 +0000

With so many new remote workers I'd love to hear how others are managing this new way of work.

My living room has now become an office/gym/living room. Separating work and life is more challenging for me now. The desk and laptop are always looming in the corner of the room.

Conversely, I tend to become more distracted without the structure of the office.

How do you all separate work from life?
How are you managing your mental health?
How are you remaining focused during the workday?

Your code should tell a story: Tips for writing code for others to read

Tom Collins — Mon, 24 Feb 2020 12:39:02 +0000

When we write code, we are also writing a story for other developers.

Here are a few tips on how we can write code for our future selves and other developers (our readers).

1. Use functions and variables to convey your intention, not comments

Relying on comments can lead to code that takes longer to read and digest. You should think about how your code will live on. It’s a story that others are going to read, possibly for years to come.

Bad:

const sendResult = (dbConfig, query) => {
  // get connection to database
  const db = getConnection(dbConfig);
  /* The function calculates exame results for all students */
  const users = db.sendQuery(query);
  const results = users.map(user => ({ id: user.id, result: result }));

  /* Generate Email with results */
  const html = generateHTML(results);
  sendEmail(html);
}

Good:
Create extra functions to explain your code. Needing to add a comment should be a call to action to either create a new variable or a new function. Smaller functions are easier to test and lead to dryer code.

const getStudentResults = (dbConfig, query) => {
  const dbConnection = getConnection(dbConfig);
  const users = dbConnection.sendQuery(dbConfig, query);
  return users.map(user => ({ id: user.id, result: result }));
}

const emailResults = () => {
  const html = generateHTML(results);
  sendEmail(html);
}

const sendResult = (dbConfig, query) => {
  const resuls = getStudentResults(dbConfig, query);
  emailResultse(resuls);
}

Good:
Documenting high level functions using something like JSDoc is an ideal use case for comments.

/**
 * Get student results from the Database
 * @param {object} dbConfig - Config for connecting to the db
 * @param {string} query - Query for the database
 */
const getStudentResults = (dbConfig, query) => { }

Disclaimer: There are a place and time for comments. I’m not against comments per se, just the overuse of them when clean code is a better option.

2. Use variables to explain control statements

When others are reading your code you should make their lives as easy as possible. I don’t want a good story ruined by constantly having to make small calculations in my head.

Bad:

const user = getStudentResults(4309394);
// I need to compute this in my brain to figure out what is happening in this if statement
if (user.result < 40 || user.attendance < 50) {
  sendEmail(user, false);
} else {
  sendPassMail(user, true)
}

Good:

Assigning new variables to store the results of a statement allows readers of your code to get on with the story. A reader of your code is trying to find the piece that they are concerned with. Help them follow the story so they can fix the bug or add that piece of functionality. This story will have co-authors.

const user = getStduentResults(4309394);
const userPassedCourse = user.result > 40 && user.attendance > 50;

if (userPassedCourse) {
  sendEmail(user, false);
} else {
  sendEmail(user, true)
}

3. Avoid ambiguous arguments

myFunction(null, undefined, 1) is not the best start to any story. Don’t make your readers delve into the function so see what the arguments do.

Bad:

const user = getStudentResults(4309394);

if (user.result > 40 && user.attendance > 5) {
// what does false mean here, I can guess but it should be explicit
  sendEmail(user, false);
} else {
  sendEmail(user, true)
}

Good:

Passing in an object can be a great solution here.

const sendEmail = ({ user, passedCourse }) => { }

const user = getStudentResults(4309394);
const userPassedCourse = user.result > 40 && user.attendance > 50;

if (userPassedCourse) {
  sendEmail({ user, passedCourse: true });
} else {
  sendEmail({ user, passedCourse: false });
}

Also Good:

You could make your story more expressive by creating some new functions.

const sendEmail = ({ user, passedCourse }) => { }

const sendPassEmail = (user) => {
  sendEmail({ user, passedCourse: true });
}

const sendFailEmail = (user) => {
  sendEmail({ user, passedCourse: false });
}

const user = getStudentResults(4309394);
const userPassedCourse = user.result > 40 && user.attendance > 50;

if (userPassedCourse) {
  sendPassedEmail(user);
} else {
  sendFailEmail(user)
}

4. Magic is good in some stories, not in ours

Avoid magic numbers. Similar to the ambiguous arguments above, magic numbers have the sort of intrigue we don’t want in our stories

Bad:

const getStudents = (courseId, fieldOfStudy) => {}

const students = getStudents('323424', 4);

Good:

const getStudents = (courseId, studentType) => {}
const courseId = '323424';
const fieldsOfStudy = {
    ENGINEERING: 4,
    BUSINESS: 5
};

const students = getStudents(courseId, fieldsOfStudy.ENGINEERING);

5. Use enums. Avoid using strings as identifiers.

In the same vein as magic numbers, using strings as identifiers can lead to confusion in your story. Having ids in strings can lead to ambiguity. Refactoring these strings will be more difficult.

Bad:

getResults({ entity: 'undergrad', courseId: 'SCIENCE_101'});

// Elsewhere in the code
getResults({ entity: 'undergrad', courseId: 'SCIENCE_101'});
getResults({ entity: 'undergrad', courseId: 'SCIENCE_100'});

Good:

const entity = {
  UNDERGRAD: 'underGrad',
  POSTGRAD: 'postGrad',
}

getResultsFromDB({ entity: entity.UNDERGRAD, courseId: 'SCIENCE_101'})

Better yet, use typescript to enforce type safety.

6. Favor verbosity over brevity

Don’t confuse your readers. Our code should be dry, concise and clean but our function names don’t need to be restricted by length.

Bad:

const results = getResults();

Good:

const examResults = getStudentExamResults();

What tips do you have?
I would love to see some code snippets in the comments.

The 10 Best Note Taking Apps for developers

Tom Collins — Mon, 06 Jan 2020 13:09:41 +0000

When looking for a note-taking app, there were a few features which I was looking for:

Markdown support - support for GitHub flavored markdown.
Organization - tagging or the ability to create a hierarchy
Inline Text Editor - being able to write markdown inline without the need for a side-by-side view.
Cross-Platform - being able to access notes on your desktop as well as when you are on the move.

Some of the things I use these apps for are: taking meeting notes, organizing my daily todo list, planning longer-term goals, collecting recipes, and planning side projects.

In no particular order here are the best note-taking apps in 2021:

1. Evernote

Platforms: Mac, Windows, Linux, Mobile, Web

Evernote is one of the most ubiquitous note-taking apps out there. It has a solid text editor with a wide variety of features, such as tables, nested lists, file attachments, and font colors. You can also set reminders on notes, something that most apps on this list do not allow.

The organization system is solid. You can create notebooks to group notes by topic. Notes can be tagged and searched by tag.

While Evernote has a solid feature set and great cross-platform support, it falls down in one key area, markdown support. I would consider this a must for any note-taking app for developers. The organization of notes is also somewhat limited in that you are restricted to notebooks and tagging.

Summary: Evernote is a solid choice if you can forgo markdown support. For non-developers, it’s a strong note-taking solution.

2. Typora

Platforms: Windows, macOS, Linux

Typora is a minimalist note-taking app available for desktop only. The inline editor is beautiful. Of all the note-taking apps I’ve tried this has one of the strongest editors. It has support for tables, various font families and nested unordered lists. Markdown works great in this editor, with a very seamless experience.

Sticking with the minimal approach, Typora allows you to organize notes using folders and subfolders. Markdown files are used under the hood for storing your notes. There is currently no tagging system which can make it difficult to organize notes across different functions.

Summary: One of the best editors on the list. A minimalist approach is taken to organizing notes.

3. OneNote

Platforms: Windows, macOS, Mobile, Web

Microsoft OneNote is a feature-rich note-taking app. It uses a similar system to Evernote for organizing notes, with notebooks being the main mechanism. OneNote does also allow you to create sub-pages though. More recent versions do have custom tags, though the UI for this is clunky.

The text editor has a large feature set. Most users will be familiar with the Microsoft Office UI. Tables, nested lists, attachments, to-do lists are all supported. There are also drawing tools, which is something that most other apps on this list are missing.

Like Evernote, a big drawback is the lack of markdown support and the plethora of features can seem overwhelming at times. I found the simpler todo apps were more pleasant to use.

Summary: A feature-rich to-do app with no markdown support. Windows users will be at home with OneNote.

4. Bear

Platforms: iOS, macOS

Bear is a beautifully crafted note-taking app. It features a fantastic inline text editor, with good markdown support. The current version of Bear is missing a few markdown features, such as tables and full support for indented lists.

The UI is excellently designed. There are a number of view options, that can allow you to move between an editor view and a menu view. The various themes help to create an excellent aesthetic. It’s clear the team behind Bear has taken great effort with the design and UX.

Where Bear really shines, is its tagging ability. You can tag notes within the editor itself using a #. Bear supports the nesting of tags allowing you to create a hierarchy while organizing your notes. Multiple tags are supported on a single note. The side menu is centered around these tags.

Bear does have a few notable drawbacks. It currently does not have an Android app or a web app. For those who are not fully bought into the Apple ecosystem, it means having Bear as your single note/todo app can be difficult.

The editor, while excellent does not have the flexibility of Notion or Slite.

Summary: A beautiful UI, fantastic text editor, and best in class tagging system make this a great choice for Apple users.

5. Notion

Platforms: Mac, Windows, Mobile, Web

The functionality of Notion goes far beyond note-taking. Its feature set boasts pages, databases, wikis, templates, todo, and boards. It offers a huge amount of flexibility and customization. Templates leverage this flexibility and provide examples of how to create pages for specific tasks. Examples of templates include a recipe book, a Kanban board or a CRM.

The inline text editor itself is very strong. It has solid markdown support and allows for multiple columns and drag n drop. It is missing a few markdown features such as proper nested lists and tables.

There are a variety of ways to organize notes. You can create pages and subpages. You can create databases with labels and links to notes. You can link pages from within other pages. Notion also allows you to share any given note or workspace with others using a shareable link or by inviting by email.

The one notable thing missing in Notion is tagging notes outside of a database. If Notion had the tagging functionality of Bear it would be close to the perfect note-taking app.

The fact that Notion themselves use the app for their support docs and release docs is a testament to how flexible the application is. This is where Notion really shines. If you want a do-it-all note-taking and organization app, look no further. It’s not the strongest in any one feature but it does most things very well.

Summary: A do-it-all note-taking app that is strong in most areas with strong cross-platform support.

6. Boost Note

Platforms: Windows, Mac, Linux, Web

Boostnote is an open-source note-taking app built for developers. It uses a straightforward side by side editor. It has good markdown support which includes tables, lists and code blocks.

The editor itself is pretty basic. For me, inline editors such as Typora and Bear offer a better note-taking experience.

Boost Note is pretty strong when it comes to organization. It allows you to tag individual notes and the side menu allows you to easily find notes by tag. You can store notes in the cloud or locally.

Summary: A note-taking app with a basic editor and good organization.

7. Notable

Platforms: Windows, Mac, Linux

Notable is very similar to Boost Notes. It has a side-by-side editor, markdown support and tags. It does outshine Boost Note on two features, its text editor and its tagging system. Nested tags are supported in Notable, a big plus on the organizational front. Its text editor has better markdown support and is easier to use than Boost Notes.

The Notable UI is simple, clean and easy to use.

There is no mobile or web version at this time.

Summary: A free no-frills note-taking app for desktop with tagging and markdown support.

8. DropBox Paper

Platforms: Web

Dropbox paper provides a great online note-taking experience. It has good markdown support and a fantastic inline editor. It allows teams to collaborate on notes with features such as commenting, todo, and sharing. The organization of notes is pretty bare bones. You can create folders and subfolders and that’s it.

Dropbox paper is currently only available on the Web; meaning that, internet access is needed when accessing your notes.

Summary: A nice online note-taking app with good collaboration tools.

9. Slite

Platforms: Windows, Mac, Mobile, Web

Slide bills itself as a collaboration tool and note-taking app all in one. It features a beautiful UI and excellent text editor. The drag and drop functionality and markdown support make this one of the strongest editors on the list.

Slite is aimed at teams. It allows you to create organizations within the app to share notes across teams. You can use Slite as a wiki for your team or as your own personal note-taking app.

Slite uses the concept of channels for organizing notes. The side menu that allows you to browse channels is beautifully designed. Unfortunately, there is no tagging support for now.

Summary: Slite is a great option for teams and organizations who want to share notes and create wikis. It has one of the strongest text editors and a beautiful UI.

10. StackEdit

Platforms: Web

StackEdit is a straightforward markdown editor that concentrates on integrating with platforms such as Google Drive, Dropbox, and GitHub.

Its UI is certainly not the prettiest on the list but as a note-taking app, it gets the job done. The editor is quick and easy to use.

The organization is basic and relies on folders with no tagging support.

Summary: A basic editor with Google Drive integration

The Winner

Many of the apps on this list focus on different areas. Several present themselves as an all-in-one solution for documentation, wikis, and note-taking. Others focus on offering an inexpensive note-taking solution specifically for developers. Each app has its own specialty and no one app performs perfectly across all areas.

I made a conscious decision to ignore the price. Most of these apps are inexpensive and if you use them correctly should be worth far more to your productivity than their price tag.

With that being said, here are my picks of the bunch:

Overall Winner: Notion

This was a close race between Note, Bear, and Slite. Notion’s flexibility and cross-platform support make it the best all-in-one solution. It has a huge feature set and a good editor. If you want to use a single app to store notes and stay you organized, look no further than Notion.

Best Editor: Dropbox Paper & Typora

There is little to choose from both of these excellent editors. Both have excellent markdown support and a clean inline editor. Typora is best if you need offline support. Dropbox wins if you want to collaborate. Slite should also get a special mention here.

Best Apple Specific App: Bear

I’m a huge fan of Bear. Its note-taking experience is great and its tagging is an excellent way of staying organized. The UI is pleasing to use and beautiful on the eye. All it is missing is cross-platform support and some extra features in the editor such as drag and drop.

Honorable mentions:

Google Keep
Ulysses
Quiver
Simple Note
Joplin
TiddlyWiki
Cherry Tree

Closing thoughts

With so many options for note-taking apps and so many features available there is a good chance that I missed out on some features. I will gladly update any of the points above to fix inaccuracies.

I use a combination of Notion and Bear. Notion for ToDo’s and project planning and Bear for note-taking.

So what is your favorite note-taking app? Comment below.

*EDIT: Update honorable mentions with suggestions from comments.

Looking back on 2019 - 7 Lessons Learnt

Tom Collins — Thu, 02 Jan 2020 12:14:29 +0000

Cross post from tcollins.dev

1. Learning shouldn’t always be about your job

In the past, I’ve always tailored my learning outside of work to what is relevant to my current work projects. I feel an important part of being a developer is to keep the passion for learning alive. For me, recently, that has meant stepping outside my comfort zone of Front End Development. This year I’ve spent time learning design principals, how to set up a web server on a VPS, and doing some writing. Of course, these do broadly relate to my field. They compliment my current skills and have the potential to open doors to other areas.

I believe continuous learning is more important than the subject matter you study. Keeping variety in my learning has helped me stay interested and motivated.

2. We should all ask more questions

If you are a Junior Developer, ask more questions. Learn as much as you can in this early part of your career. Know that imposter syndrome happens to all of us. Every developer starts off in your very position.

If you are a Senior Developer, ask more questions. You may not know as much as you think and you can always learn more. Challenge your assumptions and learn from your team.

If you are a Jedi Developer/Coding Savant, ask more questions. This will encourage more junior members to ask more questions. Discussions you start will help you, and others around you, learn.

3. Writing good code is only part of it

Clean performant code is only one piece of the puzzle. A huge part of successfully writing software is coordinating people. Having a great process around how you develop and deploy software is crucial. Motivating a team of developers will impact code quality. Organizing and coordinating a group of developers to write code in a scalable way is the cornerstone of the entire process.

4. Statically generated web pages are a great option

Static site generators are a game-changer. Frameworks like Gatsby, Hugo and Jekyll allow the advantage of automating the generation of pages without the overhead for a web server. There is often a need to have dynamic data that does not continually change, but changes according to some semi-regular event such as a blog post or a product launch. For these, statically generated pages are ideal.

6. Writing takes much longer than I expected

Planning, researching, and writing articles take far longer than I expected. As soon as I sit down to write an article, I see where the holes in my knowledge lie. This invariably leads to further research and diving down rabbit holes. Not being a natural writer, the proofreading and various drafts are somewhat onerous. Next year, I’m going to try to work on a few articles at once, in different stages, in an attempt to increase the cadence of new articles.

7. Use apps to boost my productivity

This year I’ve started using Notion and Bear for note-taking and todos, Insomnia for testing API endpoints, and Grammarly to bolster my writing skills.

Lessons from Scrum

Tom Collins — Sat, 14 Dec 2019 13:58:09 +0000

Cross post from tcollins.dev

Recently our development team switched to scrum. Before we adopted scrum we were using a more ad hoc process. We had the concept of tickets and rounds of review. There was however no strong process in place.

It has taken us a number of sprints to hone the process. Below are some of the lessons we learned along the way.

Tasks over 2 days => split them up

We primarily estimate by tasks. Each story has a number of sub-tasks. We estimate each sub-task in days. The sum of these tasks is then compared to our capacity. The textbooks will likely recommend estimating using story points. This is, of course, a valid approach; however, estimating by days has been working great for us.

If a task is longer than two days, it’s an indication that there is some complexity hidden within the task. The longer the estimate, the greater the risk that you are underestimating the time required to complete this task. If you find yourself attaching an estimate of more than two days, ask yourself: what is making this task more complex? Look at how you can split this into two or more subtasks.

Acceptance Tests are vital

One of the biggest advantages of using scrum for our team was the accuracy of requirements. Every story now has a set of acceptance tests that need to be completed in order for the story to be considered done.

An acceptance test should indicate the input and the expected output. They may also include that current state of the app. https://openclassrooms.com/en/courses/4544611-write-agile-documentation-user-stories-and-acceptance-tests/4810081-writing-acceptance-tests

The biggest advantage we saw with acceptance tests was that requirements were discussed upfront with our stakeholders. Questions, discussion, and clarifications happened at the planning stage rather than the implementation stage. This reduces the risk of bugs as well as underestimating tasks.

Having acceptance tests right there with the story is a godsend. It avoids the need to dig through docs or recall conversations on features.
Acceptance tests are also a great basis for unit tests.

Code Review Often

A by-product of having smaller tasks is that you tend to have smaller commits and conversely a shorter code review cycle. Reducing the time pull requests stay in review keeps your cadence up, and reduces the risk of large changes being required for code review changes. Large code reviews tax the reviewer. Shorter reviews will get a more thorough review, line by line, which is going to greatly help with code quality.

Aim to have several code reviews each week, or even each day. You can stub our modules that are not yet implemented and communicate this with your reviewers.

One Source of Truth

Have one source of truth. Your one source of truth should be your Scrum board. I've used physical whiteboards for this as well as digital boards.

JIRA is our source of truth but any tool you are comfortable with will work. Each story has all acceptance tests as well as links to copy docs, translations, videos, and designs. The key thing is that all assets live alongside the story itself. Gone are the days of trawling through slack conversations or emails. I can open the ticket and commence development right away.

If you use a physical board for your tickets, think about how you can manage your digital assets in an orderly way. You may elect to mirror this board in digital form. We use Google Drive, which hosts most of our content, and then link to specific Google documents in the JIRA ticket.

Do your high-risk tasks first

Unknown tasks will always have the highest likelihood of hidden complexity. It’s best to approach tasks that may look the most unpleasant or the most complex early on in the project. If you are going to overrun a deadline it’s best to know early on.
Starting with your unknown tasks gives you the opportunity to discuss requirements with stakeholders. You will have more time to clarify issues with stakeholders and fix any blocker that may arise.

Examples of high-risk tasks are tasks that have business logic, tasks dealing with data, and tasks that are outside your domain of expertise.

Demo & Deploy Often

Stick to your sprint demo schedule. Frequent demos help with communication with stakeholders. Deploying often reduces the risk of bugs being found in production.
I'm sure we have many more lessons to learn. We continually look to improve how we write software. Overall adopting scrums has been a huge win for our team and our stakeholders. By following the points above we've seen many benefits:

Happier stakeholders - Stakeholders are kept in the loop and are more active in creating requirements
Better estimation - We can now give clearer estimates to stakeholders and management. If we need more dev resources we can identify this early on.
Planning - Acceptance tests are set in advance. The requirements of each feature are clear
Happier developers - There is less context switching as all information is in JIRA. Change requests go through the backlog and planning to reduce distractions during the sprint.

My advice to you if you are not yet using Scrum/Agile, is to try it out for one project. Give yourself a number of sprints and expect to improve over time. Talk to your stakeholders and management about the advantages to them. Document the process early on and follow this process as strictly as you can. As you continue with scrum you will refine and improve this process.

Starting is the hardest part: 4 rules to stop procrastination

Tom Collins — Mon, 09 Sep 2019 17:57:10 +0000

As developers, many of us have an idea for some side project. For many this is just a thought, something that has been stewing in back of our minds. All too often, these stay as just that, ideas. Often this is due to time constraints. Work is busy, family and friends take up our time or we just don't have the energy.

There's another far more common reason. Its dam hard to get started.

Why is getting started so tough

Building habits is difficult. Studies have shown that it takes on average 21 days to build a habit. (Some guy in the pub told me that). It's the reason why it's often tough to drag ourselves to the gym or start to learn something new. We begin at first with an exuberance, which soon subsides as we realize the extent of the work involved in our new venture. We have lofty goals that we aspire to. These goals appear distant from our lowly starting point.

There is often a gap between what we want to build and what we can realistically achieve. We set out to create something ambitious, epic, game-changing but soon realize the extent of the work involved. This same conundrum befalls many a new developer. You're learning how to structure a HTML document but you want to build a single page application that you can show to your friends.

Our brain gets a similar rush of serotonin from telling people our plan as it does from executing said plan. (More barstool facts) Talking about an idea is rewarding in itself. Planning and imagining our project feels great and takes far less work. We should not linger too long in this zone of non-building.

How to get started

1. Plan, don't over-plan
Sure, dream big, have a vision, shoot for the goddam stars. Having a road map is absolutely a positive thing. Just don't over plan. Set your expectation of success. For many of us that maybe "The was harder than expected but I learned something new". Concentrate on small achieve tasks. If you build and build that success will become an inevitability.

2. Start with small and achievable
Focus on small, achievable tasks. These should be some small piece of functionality that adds a small piece of value. As much as it can this should be end to end. It should bring a user from start to finish for a single feature. Set out a number of these small achievable tasks early on. You will be able to build some momentum in this way. Once you get into a cadence of some sort you can start to plan further ahead.

Day 1 maybe create a wireframe of the first user journey. Day 2 build out your skeleton app. Day 3 get some sample data from your data source to your view.

3. Build an MVP
The best way to validate an idea is to get it out into the world. With some luck, people will see the value in your idea. Your reward circuitry in your brain will get it hit. New motivation will overcome you and you'll start on v2.

Having a goal of something deliverable early on will help steer your first feature set. By dividing an conquering what was daunting becomes more manageable.

As your building this MVP a strong focus should be making this deployable. Build this into your initial plan. Ideally, deploy each feature as they as built into a test environment.

4.When building, build towards an outcome

When you sit down to start planning/developing, have an outcome. At the early stages that may be a wireframe or a list of features to build next. Have in mind what you should have done by the end of your session.

When working with others, go into meetings with an agenda of what to discuss. Outline your desired outcomes from the start. Going into meetings everyone should know what should be taken from the meeting. After the meeting you want to be one step closer to your next milestone. Think of your desired artifacts from the meetings as being concrete actions.

…. ok then its time to stop reading and go build that project.

A portfolio template made with Gatsby

Tom Collins — Mon, 19 Aug 2019 08:16:35 +0000

A while back I came across a cool project that allows you to quickly create your own portfolio site:
https://github.com/imfunniee/gitfolio

I've been using Gatsby recently and I'm a big fan. I decided to port gitfolio over to use gatsby as its a perfect fit for a static site generator.

Clone the repo to get started on your own:
https://github.com/collinstommy/gitfolio-gatsby

Demo:
https://collinstommy.github.io/gitfolio-gatsby/

A Case Against Type Selectors

Tom Collins — Mon, 01 Jul 2019 09:58:58 +0000

I’ve been contemplating the use of type selectors in CSS recently. Below are largely opinions and I welcome comments or corrections on the topic.

So let's dig into the issue at hand, type selectors in CSS.

A common use case for type selectors is for enforcing site-wide styles. This allows you to keep things on brand by setting properties such as color, font-size, and spacing.

Let's take an example. You create some styles for our site.


h1, h2, p {
    color: '#33475b';
}
h1 {
    font-size: 3.2rem;
    font-weight: bold;
    padding: 0.5rem
}

h2 {
    font-size: 2.5rem;
}

p { 
    font-size: 1.2 rem;
}

So now we have some base styles for our elements. We want to build out some pages. Let's start with a news section. This will have some images and text.

<section class="news">
    <article>
        <h2>We're launching our new site</h2>
        <p>Check it out for lots of new content</p>
        <img sr="myimage" alt="image" />
    </article>
</section>

I want to give my news section some styles. I know I will have different types of section elements so I give this a class. Time to styles my elements:

.news {
    // p tag, have some breathing space
    p {
        padding: 0.5;
    }
    // I want my images to stand out from my text so lets give it some padding
    img { 
        padding 1rem;
    }

}

Great stuff. Now my page is ready for some new content.

After adding some content I decide that some of my articles need avatars. I want to have a series of them appear in a row.

<section class="news">
    <article>
        <h2>We're launching our new site</h2>
        <p>Check it out for lots of new content</p>
        <img sr="myimage" alt="image" />
    </article>
    <article>
            <h2>I'm a different article</h2>
      <p>but I need some avatars</p>
        <div class="news__row">
            <img sr="myimage" alt="image" />
            <img sr="myimage" alt="image" />    
        </div>
    </article>
</section>

    .news {
        &__row {
            display: flex;

            img {
                border-radius: 50%;
                width: 2rem;
            }
        }
    }

I load up my webpage. Here is where the problems start. My images have inherited this extra padding. This padding made sense for my initial design of one image per news update. It has broken my avatar design where I don’t want this spacing.

I could, of course, fix this by overriding the styles, increasing the specificity:

    .news {
        &__row {
            ...
            img {
                ...
                padding: 0;
            }
        }
    }

This is not ideal as each time I add a different child element that has an image I woul need to override this padding. This illustrates the first issue of type selector styling.

Breaking future designs

For each new case where I need different img styles in my news section, I am required to override the padding. The default I have imposed on this section only works for my initial use case. My initial use case was not a good candidate for element type styling. It was too specific and was more suited to class selectors.

By using classes I can ensure that I am being intentional when styling my elements. Aside from my site-wide typography styles, my elements will only be styled by the classes I assign to them.

Take note of the .news__avatar selector.

    .news {
        &__row {
            display: flex;
        }

        &__avatar { // no padding to override
            border-radius: 50%;
            width: 2rem;
        }

        &__feature-image {
            padding 1rem;
        }
    }

<section class="news">
    <article>
        <h2>We're launching our new site</h2>
        <p>Check it out for lots of new content</p>
        <img class="news__feature-image" sr="myimage" alt="image" />
    </article>
    <article>
        <h2>We're launching our new site</h2>
        <p>Check it out for lots of new content</p>
        <div class="news__row">
            <img class="news__avatar" src="myimage" alt="image" />
            <img class="news__avatar" src="myimage" alt="image" />  
        </div>
    </article>
</section>

By moving to use classes and BEM notation:

I’m being more intentional in the styles that I apply to the elements
When reading my markup I can see where my elements are getting styles from
I can now search my code base for __avatar. I’m helping some other poor developer who has to deal with my code

Another advantage is that my elements are styled like components. As they follow a BEM notation, moving these to reusable components is an easier task:

    const NewsItem = ({ heading, text, imageUrl }) => (<article>
        <h2>{heading}</h2>
        <p>{text}</p>
        <img class="news__feature-image" sr={imageUrl} alt="image" />
    </article>);

My feature image no longer relies on being within .news and being an img tag.

This leads to another disadvantage of type selector styling:

Reliance on element types

By tying styles to an element type I am introducing the need to change CSS if I need to add these styles to another element. Using my old element styling the following markup will require a change in CSS

If I target img my svg will not pick up the correct styles.

 <article>
        <h2>We're launchin our new site</h2>
        <p>Check it out for lots of new content</p>
        <svg ..... ></svg>
    </article>

By associating my styles with a class selector I can apply this to different element types.

<article>
        <h2>We're launchin our new site</h2>
        <p>Check it out for lots of new content</p>
        <svg class="news__feature-image" .... ></svg>
</article>

Let's take another use case. I have a span I use in my web app. It's a simple back button that triggers some javascript. I style this by using a type selector:

<section class="news">
    <span>Back</span>
</section>

.news {
    span {
        color: '#0091ae';
        text-decoration: underline;
    }
}

Later to let SEO crawlers know what this span does I change this to be anchor tag.

<section class="news">
    <a href="mysite.com/homapege">Back</a>
</section>

Again here I have broken my styles and need to change my CSS

Difficult in debugging

Consider the following code:

section {
    article {
        div {
            margin-top: 1rem;
            color: '#f2545b';
            img {
                border-radius: 3px;
            }
        }
    }
}

There are a number of issues with this. Due to the nested structure altering my DOM will break my design. Having these nested elements create a tight coupling between my styles and my DOM structure. A change in one will likely require a change in the other.

Overuse of this pattern leads to difficulty in debugging. Looking at markup without classes makes finding the applicable CSS difficult. It also requires a developer deal with specificity issues. In the future, if I refactor this CSS to be part of a reusable component, there can be an unintended consequence for child element in the DOM tree that match these elements.

Of course, the above example is somewhat contrived. Even type selectors nested a single level deep can have an unintended consequence for future markup.

In summary, avoid overuse of type selectors:

Styles are bound to specific element types
It can lead to breaking semantic markup in order to achieve a specific design e.g. <h3> <h2> in the wrong order
Changing the DOM structure can break a design
Refactoring is needed when new element types are added
Debugging can be more difficult

So what’s the solution

Lean into class names. Be intentional with your styling. There are many tools that can help you avoid names clashes in CSS such as CSS Modules, BEM, styled-components etc,
Use type selectors for their intended purpose, for applying styles globally to keep a consistent look and feel.
HTML tags are for used to semantically structure your page. A h1 should indicate the purpose of your page. A p should contain some long-form text. You should apply the styles using classes.
Create classes to reuse styles. Have a .blog__header , hero-title, big-image.

Are there cons?

Of course, as with anything, there are potential drawbacks.

Using BEM notation you may find yourself using a number of long class names: .news__article--main, .news__cta--primary
You are now required to add a class to your new elements <img class=“featured-image />

With that being said I think the improved readability, ease of debugging and more robust nature of class selectors outweigh these drawbacks.

You may argue that having to add a class to all your elements is a drawback. In my experience when there are multiple elements with the same class, this is often done programmatically or via a CMS. If you have a list of elements that you need to continually add to manually, that is a separate issue that likely should be automated in some way.

An Afterword

I believe much of the above also applies to the overuse if * > + selectors. Of course, these have their place, but should not be relied upon when a simple class would do the job. Using a variety of selectors in your code makes developers reading your code have to constantly compute what these selectors are doing. Often the best solution is the simplest one.