TL;DR
I'm keen on gathering software best practices to shape them into Standards as an open source project with GitHub Standards. The following table shows what I got so far on the proof-of-concept Javascript standard:
| Required | Description | Subtype |
|---|---|---|
| Yes | IDE configuration (.editorconfig recommended): In order to maintain certain level of consistency when developing on any IDE. This is related to the linting point too. |
parent |
| Yes | Linting methods (.eslint recommended): In order to assure certain level of consistency throughout the code. |
parent |
| Yes | A package.json file needs to exist to describe basic information about the project. The mandatory properties are: name, version, main, private, description and repository. The version needs to follow SemVer convention. |
parent |
| No | Code modularization (commonjs via webpack recommended): In order to organize your code and provide a clean way of dependencies throughout the project. It's optional as no every Javascript project needs modularization. | app, library |
| Yes (3) | Run scripts: In order to prepare the project to be usable to others. If a package.json is present, these scripts should exist depending on the type of project:
|
parent |
| No | Use ES2017 (babel and ES2017 preset recommended): In order to have the best tools to develop Javascript projects with latest effective additions. It's optional as not everyone knows the latest ES standard and not every project needs the latest tools to work effectively. | parent |
| Yes | Handling dependencies in devDependencies and dependencies depending on whether they are needed for setting up the project environment or the content in the project itself.
|
parent |
Please feel free to contribute on the Javascript standard proposal >>here<<.
Introduction
For a while now, 4 years to be exact, I’ve been working on multiple projects within a huge company. It’s been a roller coaster to say the least, and the feeling I remember experiencing the most when having to create a new piece of software, that was supposed to serve other teams as well, was (and still is) the same: uncertainty.
Somehow, the team and I needed to architect an application or library that should work as good as possible, cover all use cases as perfect as possible, be tested as much as possible and be as flexible as possible to be prepared for any turn of events. And, as if that was not enough, it should have the best way to interact with a third-party application or library without having any time to figure out how it is constructed or even know which third-party app or library could potentially require doing so.
The years passed, the situation remained. But then, this company decided to changed its DNA: from license-based to subscription-based. And that came with a whole new different way to think about software. In short, the most important thing to do to be successful with this new DNA was collaboration between peers in order to achieve the best synergy possible between products.
This new direction sounds really good, and I want to be part of it for sure, wouldn’t miss it for the world... but the uncertainty I felt is not going away that easy unfortunately. And I wanted to do something about that, and not just for myself, but for every other co-worker as well if I could. Then, I remembered another change of DNA I experienced recently as well.
I work for this huge company through Globant, and it recently changed its DNA too in order to not just injecting innovation to its clients as we all grown to do, but also “create digital journeys that matters to millions of users”.
In this case, I’m interested in doing that for my fellow co-workers, because a good customer experience starts with a good employee experience, and by extension, a good customer experience starts with a good developer experience.
That is how I eagerly started thinking of a plan that could eradicate my deep-set uncertainty, an accessible plan, easily extendable and astonishingly scalable. Not an easy task if you ask me, but I love challenges.
This is what I came up with... ground rules in form of standards.
What is a Standard?
According to Wikipedia, a Software standard is:
“[..] common format of a document [..] accepted and used by one or more software developers while working on one or more than one computer programs. Software standards enable interoperability between different programs created by different developers.”
The key concept for this initiative is “interoperability”. Being able to generate a piece of software that followed pre-established conventions we all agree upon to:
- measure quality in some way;
- assist a developer in understanding what the piece of software provides in order to facilitate usage;
- provide an understandable and universally accepted way to collaborate on any type of project;
- promote a healthy way to extend any software when collaboration guidelines are followed;
- bring up to speed any new developer by reading the standards applied.
In essence, a standard should describe best practices, taking into account latest trends on how to develop a piece of software so that it works as good as possible. It should describe every process to create the most interoperable software as possible, including processes that could assure its quality as well as procedures to publish so that it becomes available for its usage.
How should it work?
First of all, these standards needs to be developed by the developer community, each one contributing constructively on any aspect on any standard they acquired knowledge about in order to be able to contribute towards generating valid, up-to-date and usable standards.
Secondly, by its collaborative nature, a standard cannot be imposed, crafted single-handed and distributed as a commandment. Any interested party should be able to contribute freely, following collaboration guidelines to propose changes, others could up-vote or give any sort of feedback so that ultimately certain designated authors can approve those changes to be included to the standard.
Last but not least, standards needs to be promoted and viralized inside its community so others could know they exist, pitch in to existing standards or create new standards and apply them. There is no use if just a bunch of people know they exist and adopt it on their projects, the more the better. We all know the standards-related XKCD.
Not to mention that ideally any third-party app or library consuming your piece of software needs to know they are consuming something well made, safe and stable, and so on.
So, summing up:
- Community-wide
- Community-driven
- Community-promoted
Let’s dig in into how could we solve these aspects.
Community-wide
I’ve been thinking about which tool fits best when we talk about a developer community. It’s definitely not Wiki pages, they are difficult to maintain and not very intuitive for developers. Well, a very intuitive tool for developers that is also available is Github. Developers already know how to use it, there is a pretty neat established way to collaborate through Pull Requests, versioning is built-in, it provides a way to generate viewable and presentable content through Github Pages if needed and it handles fine-grained permission and security. So, in order to reach the majority of the audience to become community-wide, using Github is the way to go.
Community-driven
As mentioned before, there is an excellent established way to collaborate through Pull Requests. Also, Github Issues provides a really good way to interact with a standard in the form of a repository. These Github Issues could be categorized with tags and promote a healthy discussion. Basically, the developers could own their ideas and share them easily, driving the whole initiative forward.
Community-promoted
It is very important to let others know about the initiative, not only by peer-to-peer interactions, but also include visual aids; that are those badges I mentioned earlier. This is so that others could verify that certain library follows best practices that a group of specialized people put together collaboratively, and also, to create the urge to do the same thing and apply a standard or create one.
This kind of behavior is already installed on the Github community and it uses badges:
These are little images that informs something very specific, and are added to the top of the README file.
What's next
- Receive feedback about this initiative to adjust what’s necessary
- Have other people excited and willing to help with this initiative
- Work on some proof-of-concepts standards that could also help shape the meta-standard. Currently the first standard proposal is for Javascript projects.
Top comments (0)