Categories
Articles

Mind maps in Spacemacs

This post is the second in the series of posts called PlantUML in Spacemacs. In this post we are going to see how we can create awesome Mind maps in Spacemacs using PlantUML. Mind map diagrams is the new feature recently rolled out in PlantUML and they are still in the beta* stage.

And you will find only minimal documentation in the official site related to mind map diagrams. This post gives you some additional bonus information such as adding colors to your mind map, creating high resolution mind maps and so on. You can find all these details in the Advanced Usage section in the bottom of the post.

If you want to know how to setup PlantUML in Spacemacs, please visit our previous post in this series.

Spacemacs

Spacemacs is a community-driven Emacs distribution. It is a new way to experience Emacs with a sophisticated and polished set-up focused on ergonomics, mnemonics and consistency.

Mind maps

A mind map is a diagram used to visually organize information. A mind map is hierarchical and shows relationships among pieces of the whole. It is often created around a single concept, drawn as an image in the center of a blank page, to which associated representations of ideas such as images, words and parts of words are added. Major ideas are connected directly to the central concept, and other ideas branch out from those major ideas.

1200px-Tennis-mindmap.png

Although the term “mind map” was first popularized by British popular psychology author and television personality Tony Buzan, the use of diagrams that visually “map” information using branching and radial maps traces back centuries.

OrgMode syntax

Mind maps in PlantUML support the org-mode syntax also, which means you can easily create mind maps if you know understand the standard org-mode conventions for outlining. This will be an added advantage for people who are already familiar with Emacs and org-mode syntax.

Removing box

You can remove the box drawing using an underscore.

Arithmetic notation

You can use the following notation to choose diagram side.

Markdown syntax

This syntax is compatible with Markdown.

Changing diagram direction

It is possible to use both sides of the diagram.

Complete Example

Here is the complete example of a mind map with all the options which can be provided for your mind maps like caption, title, header, footer and legends.

Advanced Usage

So far we have only seen the examples provided by the official docs for Mind maps in PlantUML. Now we move into more advanced usage like colors, style and other stuff which will be very helpful for people instead of boring monotonously colored mind maps.

First we will jump into the colors section which is my favorite one, because I want my mind maps to be more colorful because that was the original idea proposed by Tony Buzan in his book called The Speed Reading Book.

Colors

With PlantUML, you can use specify a color using any one of the below methods:

  • with its standard name
  • using HEX value #AABBCC
  • using short HEX value #ABC

You can visit the official colors page in PlantUML for the list of color names you can use.

Changing background color

You can also change the entire background color of your mind maps other than the default white color using skinparam. skinparam is a command to change colors and fonts for the drawing.

You can use this command:

  • In the diagram definition, like any other commands,
  • In an included file,
  • In a configuration file, provided in the command line or the ANT task

Changing color of each node

If you want to change the color of each of the nodes in your mind map tree, you can do so by giving the color option within each node like below. Again you can use any of the three options such as color names, short and long HEX values.

Using color names:

Using HEX values:

Shorthand hex notation abbreviates 6-character RRGGBB CSS colors into 3-character RGB shorthand. So the color value ##FF6600 becomes #F60 in the shorthand notation.

Using short version HEX values:

Creating Monochrome Mind Map

If you are a person who cares about the environment, who don’t want to waste the color inks in your printer, you can choose to generate your mind maps in monochrome version like black/white with the monochrome skinparam command.

Handwritten style

If you want your mind maps to look realistic or you are not comfortable with computer-generated mind maps, or you want a natural feel to your mind maps so that they will look like they are hand drawn, then you need to configure your mind map generation with the handwritten skinparam.

By default this property will be false and if you want handwritten style mind maps you can set it to true.

Disabling Shadows

You can disable shadows from your mind map items with the option called shadowing. Again it is a skinparam command with a Boolean value. To disable shadows you need to explicitly set them to false.

Creating Print resolution Mind Map

By default, the default resolution for the image generated using PlantUML will be 72 which is the default resolution for digital media and the size of your mind maps will be determined by the content it has such as how big the tree is or how many number of nodes or leafs you have in it.

This option called dpi will come in handy if you want to take a print out of your mind maps and hang it in your favorite place so that you can take a look at them at your convenience.

DPI or Dots per inch is a measure of spatial printing or video or image scanner dot density, in particular the number of individual dots that can be placed in a line within the span of 1 inch.

For print material, the ideal resolution needed is 300 which you can set it via the dpi skinparam command.

Hope you enjoyed the post and it will help you to create awesome Mind maps from within your favorite editor. Please let me know your feedback or queries in the comments. Stay tuned for more in this series on other cool stuff you can do with PlantUML.

References

Categories
Articles

PlantUML in Spacemacs

This article is the first in the series of articles about including and using PlantUML in Spacemacs to do some amazing things. In this article we will see how to setup PlantUML in Spacemacs and use it. In the upcoming posts we will see some advanced usage of PlantUML and some awesome stuff you can do with it.

Spacemacs

Spacemacs is a community-driven Emacs distribution. It is a new way to experience Emacs with a sophisticated and polished set-up focused on ergonomics, mnemonics and consistency.

PlantUML

PlantUML is an open-source tool allowing users to create UML diagrams from a plain text language. The language of PlantUML is an example of a Domain-specific language. It uses Graphviz software to lay out its diagrams. It has been used to allow people with visual disabilities to work with UML.

It has got hundreds of ways to integrate with your text editors, code editors, command-line, browsers and so on.

plantuml-mode

plantuml-mode is a major mode for editing PlantUML sources in Emacs developed by Carlo Sciolla from Amsterdam. It has got features like syntax highlighting, auto-completion and preview of buffer or region.

Installing in Emacs

Enable the major mode

You can automatically enable plantuml-mode for files with extension .plantuml by adding the following to your .emacsrc:

Of course, you can always enable manually the major mode by typing M-x plantuml-mode once in the desired PlantUML file buffer.

Spacemacs plantuml layer

This layer enables support for plantuml-mode in Spacemacs. To use this you have to add the plantuml layer to your dotspacemacs-configuration-layer in .spacemacs. You can open your .spacemacs file by pressing Spc-fed, and update it like below:

Installation

Recently, plantuml-mode have rolled out a new update for an experimental feature called Execution modes. Like you can choose any of the two existing mode to render the preview of your PlantUML code. Spacemacs still hasn’t updated to this change I guess. So if you are using the layer option to enable PlantUML you need to set the default execution mode to jar, so that you can use your local jar file to render the preview rather than using the server.

You can add this below snippet to your dotspacemacs/user-config

Also, to enable preview you need to tell plantuml-mode where to locate the PlantUML JAR file. By default it will look for it in ~/plantuml.jar, but you can specify any location with:

This is all you need to set up PlantUML in Spacemacs.

Preview

Once you enabled the plantuml layer, you can start using it by creating files with .pum extension. Spacemacs will automatically enable the plantuml-mode for you.

To render the PlantUML diagram within Emacs, you can hit M-x plantuml-preview.

Now open a new file/buffer and type the below code and save it with any name with .pumextension.

Now if you render the preview using Spc-mcc, you can see the below rendered image. This will run PlantUML and display the result in the PLANTUML-Preview buffer.

You can save the image buffer as a PNG file using Spc-fs with a .png extension.

That’s it. We will how you can draw more different type of diagrams with PlantUML from your favorite editor itself. Stay Tuned!

Please let me know your feedback/queries in the comments.

References:

Categories
Articles EmberJS

Ember into Futurity

Nobody can predict the future, but everybody can wish for something in it. It could be for the benefit and interest of one person or a community as a whole. I am putting down my thoughts and wishes for Ember.js as both a consumer of the framework itself and producer of the supporting tools and addons for the same.

The best way to predict the future is to invent it.

This post is my answer to the call for blog posts for #EmberJS2019. I haven’t had the slightest idea to write a post for the blog post call, but my colleagues and friends insisted me to write one. Because honestly I really don’t know where to start and how to give a conclusive ending to my post. But my creative Muse never ceases to amaze me. So here it goes.

The Framework

As a framework, we need to fully achieve conceptual integrity on what we want to accomplish and how we want to move forward with it. Because instead of trying to become one “All Purpose Tool Kit”, we should focus on one thing and do it well.

Ember has the right ideas, but the wrong atomic structure.

Component Paradigm

While Ember was ruling the MVC realms, there came a knight known as “React“, armed with a simple yet profound idea, who taught us how we can build web applications using components. The Components Model may be a new one for Web development, but it wasn’t for programmers and system application developers like me who have been dealing with objects and classes for a very long time. Yet this new Knight conquered the world with his deep and extensive conceptual integrity. Ember failed to realize this threat for a very long time, even though Ember had components in it’s arsenal, but it was no match for React.

Octane

Octane is the one thing I eagerly waited for in Ember a year ago when Tom Dale published his Ember 2018 Roadmap RFC. I even remember that I explored the RFC in detail in my blog here. But still we are yet to see a full-blown Octane Edition landing in Ember. And it would be a disgrace if I fail to appreciate the effort put by the Team to make the necessary provisions for the Octane release by making the guides ready with great care and great tact.

More Flexible CLI

One of the best things I love about Ember is the CLI. No other Javascript Framework has got it right till date. While all of the other frameworks use CLI as just an application scaffolding tool to bootstrap a project, Ember-CLI goes beyond them with generators and blueprints. And it gets even better by giving us the flexibility to define and generate a custom blueprint.

But the CLI is not very flexible in-terms of choosing tools and libraries for various tasks other than the standard packages shipped as part of the CLI. The Convention over Configuration is holding us back in some aspects on this front. The Web is evolving with more new tools and libraries day by day, and I think we should open up more and make provisions to allow developers to choose their own tools and libraries best suited for their projects.

We should adopt the ideas from projects like ember-cli-create which will allow the developers to choose their own tools and technologies for their projects based on the requirements, platform and other external factors.

Unified Documentation

This is one thing I really wanted to emphasize here. Because we have so many ideas being implemented in Ember such as Server-Side Rendering (Fastboot), Ember Engines and Glimmer.js. But all of them are scattered and fragmented. I wish all the above things should branch out from our main guides for Ember instead of having separate websites.

I am not concerned more on the technical implementation rather on the conceptual mapping to give developers an overall idea of different technologies that can be used along with the framework. It could be a simple page for each one of the above within guides itself and guide the users to take them to the main website if they want to explore more on this or a more prominent place where we can have links to these projects within the guides itself.

Functional Components (Hooks)

When hooks landed in React, it made a real fuzz. More of my fellow React developers were singing praises for the same, such as how it changed the way they write code and mutated their minds on how you could bring about solutions for complex problems using components. And again underneath all the fuzz, it’s just a conceptual modification that the React framework brought in for writing components, which can be adapted to any framework that supports the component model for creating user interfaces for the web.

I wish Ember could have adopted it much earlier, but it’s better late than never. I am very much relieved to see this has seen the light of the day, when I saw ember-functional-component  created by our beloved rwjblue.

Fail Fast

As a community we value “Stability without Stagnation”, but that proved expensive for the framework in the long run. I personally urge that we should fail fast, because by failing fast we come to value the lessons and insights we learnt from our failures and move forward with much greater pace. We need to get out there, try out new things and find out what works and what doesn’t.

Why do we fall? So we can learn to pick ourselves up.

– Alfred, Batman

Embroider

Using broccoli as a build tool, have been a huge impediment for Ember, in adopting the best and the latest conventions from other frameworks in terms of build pipeline and tooling. Since other frameworks like React, Angular and Vue are heavily betting on cutting edge packaging technologies like Webpack, Rollup and Parcel, while Ember still fixating on broccoli proved to be a costly mistake for the community. I think Embroider will not suffer from the same fate, by adopting Webpack as a tool in the build pipeline.

Conclusion

So instead of asking “Why didn’t Ember succeed?”, actually the right question to ask will be Why is there a perception that Ember didn’t “succeed”? And I would like to conclude this post with words from my favorite author, Henry David Thoreau.

Read your fate, see what is before you and walk on into futurity.

Categories
Articles Uncategorized

24 ways for being productive with big code base

In this article we will take a look at some of the guiding principles which are beneficial while working with large code base.

The whole idea of this post is to collect and come up with a checklist of significant approaches and ways to deal with large and legacy code bases.

The readers are welcome to share more tools, methods and approaches in the comments section below.

1. Onboarding Documentation

Ask if there is onboarding documentation, or someone who can give you a high-level overview of the codebase. Typically finding a person with a lot of context on the code is the fastest and most thorough way to understand the responsibilities and layouts of a codebase. Ask if they can draw an ER(Entity Relationship) diagram, it’s extremely valuable documentation for any additional developers.

Show me your flowcharts and conceal your tables, and I shall continue to be mystified.

Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.

— Fred Brooks

2. Read Documentation

Read all the documentation possible, especially design documentation. This should hopefully give you some clues as to both function (what) and purpose (why). The discussion around this will also introduce you to the major players in the architecture of the codebase.

Documentation is the castor oil of programming.

— Gerald Weinberg, The Psychology of Computer Programming

Note this does not necessarily mean formalized design docs, it could just be searching for any README’s or relevant wiki pages. You’re just gathering threads at this point, and documentation tends to be a lot more compact and easily digestible than foreign code.

3. Look at the models

Look at the models – there will be compact representations of data at some point. This gives good insight into the shared language of the code and can give a lot of clues about how things are done. They also tend to be a lot more human-readable than other pieces of code, so this is a plus.

The architectural model provides a Gestalt view of the system, allowing the developer to examine it as a whole.

— Scott Ambler, Agile Modeling

4. Find and Skim the largest files.

Typically these files perform the majority of the work, have the most responsibility, and introduce most bugs. Knowing roughly where the major players are and what they do makes it a lot easier to read any individual file.

You need to be fully aware of the presence of any God Class or components in your codebase which pose a serious threat to the long-term health of your product.

5. Run the application

Run the application, find some small behavior (a single, simple endpoint) and debug it. Step through the application code so you can see how a particular request flows through the system. This can show you how a lot of different concerns within the code are tied together and also ensures that you’re set up for both running and debugging the codebase.

6. Don’t plan a full rewrite

Don’t plan or do a full rewrite – it’ll almost never work. Jeremy Burton has this wonderful postdiscussing the social and economical impacts of code re-writes.

When you inevitably come across a trade off, choose the one which is easiest to change later. Everything else is just noise. Large changes in legacy systems often suffer from the second system effect among other problems.

7. Learn the tools

Learn and use tools to automate the build system and quality assurance (JenkinsSonarqube,DockerGit, etc.)

Great tools let us do the impractical and the impossible. They give us super powers. The goal should be to know your tools so well that you can focus on the work at hand, without having to think — they should be second nature.

8. Sharpen the saw

Sharpen the Saw means preserving and enhancing the greatest asset you have–you. It means having a balanced program for self-renewal. It is the mindset to seek continuous improvement and renew yourself professionally.

Give me six hours to chop down a tree and I will spend the first four sharpening the axe.

— Abraham Lincoln

Take the time to improve your skills and the skills of your team (coding dojos, experiments). An excuse to not sharpen the saw is an excuse for failure, burnout, and mediocrity.

9. Spend time with your end users/customers

If possible spend time with the main user / product owner (especially in peak periods). You’re blessed to have users, who understand your system.

The team is actively encouraged to spend time with actual customers to learn more about their needs. A developer may spend time observing real users and come away with brilliant insight into what is most needed.

10. Focus on cross cutting concerns

The crosscutting concern also known as system-wide concern is a concern which is applicable throughout the application and it affects the entire application. These are the concerns representing functionalities for secondary requirements. These are typically implementation details that need to be kept separate from business logic. Do refactoring and first focus on cross cutting concerns (APIs, translations, caching, logging, database, etc.)

11. Migrations

Migrate things to well tested isolated APIs (e.g. use REST / Graphql APIs with new endpoints in the frontend and try not to use untested code for these APIs). It is always a good idea to have a strategic plan for migrations in your development roadmap. It could be every 6 weeks or 6 months, but it should be done at regular intervals of time or else you will be incurring a large amount of tech debt in your codebase.

12. Move fast and break things

Don’t be too backwards compatible (move fast and break things) This way of working usually emphasizes testing out new ideas, iterating quickly based on data, and aiming for more frequent points of learning. Allen Yang exhaustively discusses the pros and cons of this approach in this Forbes article.

13. Get the team on board

If there are multiple people you need their buy-in and support for whatever approaches you want to do

14. Plan for “health by a thousand small improvements”

It will be an iterative approach and you will refactor as you go.

15. Don’t assume different = bad

People might have done differently, consider using their approaches. You might do it differently. But it’s better if you keep a consistency within the codebase. In codebase management consistency trumps cleverness.

16. Create space

Consider introducing a Fix-it Friday where everyone can work on little improvements. Think about conducting a bug-bash in your organization, at regular intervals of time so that it automatically creates a platform where all the developers, testers, program managers, usability researchers, designers, put aside their regular day-to-day duties and “pound on the product”.

Because each person will use the product in slightly different (or very different) ways, and the product is getting a great deal of use in a short amount of time, this approach may reveal bugs relatively quickly.

17. Create a Non-Blame culture

Stuff will break if people risk improving things. Avoid blame shifted to them. If bug trackers ping individual people consider pinging the whole team instead.

If you get your ego in your way, you will only look to other people and circumstances to blame.

Jocko Willink

18. Consider automation

While “development automation” is not a commonly used and recognized term of the software development industry, business people normally use it to refer to “anything that can speed up the development process and allow the organisation to bypass most, if not all, of the software development process, jumping from a simple business-level wish list to a ready-for-the-market product (writing as little code as possible and hiring as little programmers as possible)”.

Any technology/methodology that can reduce software development to the most complicated thing the average business guy can understand.

Here are some examples of development automation:

  • Automatic update of dependencies
  • Automatic build process
  • Automatic checking of style rules
  • Automatic execution of unit tests with every build
  • Automatic update of code-generated proxies
  • Automatic creation of deployment packages
  • Automatic configuration of target environments
  • Automatic deployment to development or QA environments
  • Automatic computation of metrics, such as Code Coverage
  • Automatic smoke tests
  • Automatic generation of release notes, or at least of the bug list that goes in the “Fixed in this build” section

19. Start with the tests

This one is the most annoying, but worth doing. Whenever you improve a feature a bit try adding a test. Often in legacy apps there are no good tests. A lot of people recommend writing a test suite for the whole app before you do anything. If you are lucky enough to do this try it. The iterative approach more realistic as you can also do feature work while refactoring.

When doing tests focus on integration (vertical/functional/etc) and not unit tests (unless the “unit” contains critical or complex logic). Your goal is to know “that you broke something” – you get by if you don’t always know “what you broke“.

Write automated tests (unit, integration, acceptance) for existing code where ever possible. Write at least unit tests and integration tests for new code.

Make sure you have development and test environment available, including data transfer from production to test.

20. Acknowledge tech debt

Not everything needs refactoring. If it’s not critical and nobody needs to touch it consider acknowledging it as tech debt. Add larger notes above the problematic areas and explain why you aren’t refactoring it, explain things worth knowing to understand the code better, etc. Whenever you leave comments remember that comments should explain “why” not “what” the code does.

21. Read a lot of code

Spend time reading code in the codebase even if it does not seem to make sense, even if you don’t think you’ll need to know that part of the code. Keep reading until it starts to make sense. The trick is to just read. You can even avoid tools that automatically navigate the code because you will know eventually where things are.

22. Debugger is your BFF

The first and the foremost task while working with existing code bases is you need to get debugger working. Nothing can explain the processing workflow better than tracing the execution.

Get familiar with your debugger. You may be surprised by how deep in a call stack a bug can live. It will also make you intimate with the different ways your codebase is orchestrated together. Also having any kind of schemas, protocol definitions and tests can help grasp whats happening in the system.

23. Use the boyscout approach

Clean where other left dirty stuff. Sure, many here would argue that “never touch a running system” is a gold rule, but what if the running system is running in the wrong way?

The Boyscout rule

Always leave the campground cleaner than you found it.

If everyone attain her/himself to this rule, there wouldn’t be what we call innovation.

24. Don’t try to fix the pile of mud

Complicated software are infections of a complicated business requirements. When something is a pile of mud, don’t try to fix the mud.

Fix the business requirements until it get easier to handle. This also leads, most of the time, to a massive reduction in messy code bases.

At this point you should have a fairly solid understanding of at least the most critical points of the codebase, and also be set up to run and debug it. You should also have at least one or two points of contact to ask questions. This gives you a good framework for figuring out how to modify the codebase moving forward.