Today I have stumbled upon a great article by Austin Z. Henley called "Can you make a basic web app without googling?" read it.
The article pretty much sums up what is, in a way, wrong with software development nowadays. Not looking far away, i can tell you how my work looked like in some of teams I have worked in. To add almost any feature I had to Google for technical nuances to find the solution I needed for the given stack. Than I had to look at the documentation, source code, ask several coworkers for additional information. Just to add one little thing.
For a lot of developers out there it seems like a normal way of doing their job. Spending 90% of time on preparations and information gathering, and 10% on the actual implementation. The proportion becomes even worse if there is someone who has to make a business decision or you have to wait for other things to happen first.
But the question is, if there is really no other way to approach problems? With several teams i have created during my career, we were able to set up a working environment that lowers preparation costs. The most important way to improve the productivity of a team, is to give every member the right to improve project, either by adding tests, comments, or documentation each time, it took too long to find the answer. Contrary - any limitations make developers either not note their know-how anywhere or putting them in places they are not looking up later.
One problem that especially gained my attention lately was to find a way, to enable each team member, but also whole team know how inside the source code. In my experience it is the right thing to store it for productivity purpose, because it is the place every developer has in front of his/hers eyes.
You may consider - why not use comments and structured comments that generate documentation for that purpose? The answer is that often, know-how is not something we consider a comment a good place for it. Let we look at some examples:
1) An application you are developing uses a set of icons. If you can not find one, that is required by the design, you have to contact John, receive the icon, make sure it has proper format, and put it into a /src/internal/images/icons folder before calling generateIcons script. Often people are stuck at the process, because they forget about something. New members have to learn the process from other members.
2) The application contains a specific interface IWiredEnumerable instead of standard IEnumerable. Everyone should use the interface as a business requirement. But team members forget about it often.
3) You often have to use a method defined in an external library. However the method is not documented, so you end up DuckDuckIng documentation every time you use it.
Now imagine, that before you have wrote some info for you, or for other team members to solve these issue. Where would you place it?
This is how Assistant extension for Visual Studio Code was invented.
How Assistant works?
Let's go over situations described above, to show how the extension works.
Solution to 1)
For the first situation you'd like to make sure all members know how to prepare an icon, but you don't want to put a lengthy comment in the code. Also, you know looking through the documentation will take time. So you decide to assist developer when he/she looks at Icon class constructor:
when: developer views Icon class constructor
than: show message: if icon is not available in /src/internal/images/icons, contact John, make sure he sends SVG. Put it into the above folder and call generateIcons.
Result: every time a a developer looks a the Icon class constructor, above the line, he/she will see your assistance message. It will be placed in the source code editor above constructor line. It is impossible to miss out!
Also, since the rule is stored separately than the source code, it does not have to comply to comments and structured comments good practices or even your team specific rules. You are fine to mention John, and give every hint you find useful for the particular situation!
The example perfectly shows how having Assistant rules liberates team members and embraces everyone to improve coding flow of every developer! He/she does not look in any other place to find the piece of a really important business logic!
Solution 2)
You want to recall every developer to use IWiredEnumerable instead of standard IEnumerable. You decide to assist developers:
when: developer tries to create object and assign to IEnumerable type
than: display a message to use IWiredEnumerable that takes care about integrity
Result: if the developer won't remember about using the IWiredEnumerable, he will finish the code with IEnumerable. Maybe, he/she will spend some time duplicating features of IWiredEnumerable. Than will commit the change, and learn about the rule during a code review. Or even worse: the change will be merged eroding the code standards. Either way the developer will have to spend additional time to rewrite the code to use IWiredEnumerable increasing the risk for mistakes and lowering the performance.
However, with Assistant rule, the developer will know to use IWiredEnumerable as soon as trying to assign to IEnumerable type. He/she will be happy to switch immediately to the proper interface and finish the task earlier, because IWiredEnumerable contains part of the things he/she expected to write on its own.
Discussion: such rules can be introduced also with regular linters. However you should be aware writing linter rules is not trivial. Every developer has to learn it to contribute to the know how.
On the other hand, with Assistant, all you have to write is a rule and message. The rule can be even "IEnumerable<" since it will match every time someone tries to create to assign to IEnumerable. The overheat to write an assistant rule is almost zero.
Solution to 3)
That example is one of my favorites. You have once for a while to use an external method called getCost(distance, type,...) located in an external library. Your client shares the method to allow everyone to calculate employee travel cost. All you have to provide is the distance and type. However it is not documented. It accepts kilometers as the distance, and type='e' for external employees and type='i' for internal ones.
Also it has five more arguments we will ommit now. What you want to make sure is that every developer, including you, will be reminded distance is in kilometers. Especially since you are using meters and miles in your project. Also you'd like to describe other parameters, you use the most to save some time.
You decide to write an Assistant rule:
when: a developer writes " getCost("
than: show a message indicating first parameter is distance in kilometers, what values type accepts etc.
Result: every time you or other developer has to call getCost(, he/she sees an information about parameters. That way the risk of wrong metric unit is lowered, and also productivity is increased because DuckDucking is not required anymore.
Discussion: The example assumes that you can not write a method that calls getCost() and document it properly. It is the limitation of the example. However still, you can notice that some information about parameters can not fit into formal requirements your team uses for comments and structured comments generating documentation.
With Assistant you don't have to care what are the formal rules. You don't have to defend each useful comment you write and waste your energy and time for such nonsense. As the developer, you know what knowledge helps you the most.
You can gather know-how for your own benefit. It can be stored in personal or preferences project file. None of these has to be committed to the repository. However, when you gather some know-how it is great to introduce the way of work to the whole team, so everyone can enjoy not Googling! Than, the team can share common know-how file, while each member has still a private space for his own know-how.
Extensibility
I am using Assistant now for several months for several projects, and it saved me a lot of Googling. Every time I stumble upon on a knowledge to gather I create a rule. Than, it pays off nicely, when I have every information in place. Also I have onboarded new developers with Assistant rules, and it helped greatly to lower the time to make valuable contributions.
Since rules can be written as a regular text, or Regex, it is really easy to create them. Also Regex gives some really interesting ways to use the extension for more complex problems.
If you like the concept, check the extension out: Assistant, since it is free and open source, you are welcome to contribute, either with ideas for new features or code contributions. The source code is pretty easy to play with.
However, if you just want to try it out, all you have to do is install it, and write a simple rule. In case you don't have any ideas, just download some rules that are available at the plugin page.
Top comments (0)