Strategies for documenting code

Sukhpreet Singh — Tue, 15 Nov 2022 05:09:14 +0000

Documentation aims at explaining how the code works, and how to use it.

Let's look at some ways to document your code:

comments :- put some comments (something is better than nothing), because it would helpful for your future self, and others who are going to work on it.
providing images, block schemes, diagrams, links and references to cool reference, where it's explained more in details (might be place from where you learned it.)
README files containing all the necessary information about code utilization
release notes/changelogs will help developer to get where the stuff is heading toward what is the recent progress.

Pros & Cons

Documenting your code is an important skill to have, some need to practice it, and some born with it.

Pros

Saves time, when you next time need to make changes to it.
helps to refresh your memory
helps to fix bugs
allows for version control
Helps others to go deep into your code, and motivates them to contributes.

Cons

takes a lot of time and patience to write good documentation.
easily becomes outdated, so needs to be updated all the time
constant feedback is needed to make it genuinely good which is usually hard to get, for small teams.
Boring!!!

Astro 🚀 🚀 🚀 Framework

Sukhpreet Singh — Tue, 17 Aug 2021 17:14:41 +0000

You can use any framework you want (or none at all)

#### 🤩 Really Awesome Not!

#### 🤔 But will it not create a mess

#### 🤗 But still pretty powerfull

Yes! it is powerful 🦄 for a person who has experience with the framework that he is going to use
but still For Example knowing that svelte framework is very good at animating stuff is pretty powerful to use it with other stuff who have to make your website .
You can use many libraries at the same time in your website from different frameworks, But still use things which you are going to use most of time don't install
4 to 5 UI libraries from different frameworks, If you do then you can't use one of them to it's capacity .
And more libraries will create more confusion So, make a mind map before installing libraries
Take a look at frameworks which you are going to use and Where you like to use with Astro .
In most scenarios One framework is enough or Two framework .

In Comming year there are many tools comming, and already we have a ton of tools So,
The thing that matter is your vesion that how to use them at right place to look and work pretty smooth .
But still these tools are going to make life easier .

Let's work with an svelte Exampl

In This example I am going to show you how to make a svelte component
that will animate underline with rough-notation
Pure Javascript Library

  <script>
    import { onMount } from 'svelte';
    import { annotate } from 'rough-notation';
    let e;
    onMount(()=>{
      // a for annotation
      const a = annotate( e, {
        type:'underline',
        color: '#FFF',
        rtl:false,
        animate:true,
        padding:10,
        animationDuration:500,
        iterations:2,
      });
      a.show();
    });
  </script>
  <button bind:this={e}>
    <slot/>
  </button>

Now you can use this component in your Astro file like this

---
  import MakeItUnderlineAnimate from "./yourSvelteFile.svelte" 
---
<MakeItUnderlineAnimate client:visible >
    iAmUnderlined word
</MakeItUnderlineAnimate>

Making it a Reuseable component

Reuseable components are great only if they are flexible
Let's make our component Reuseable

Let's see what we can change in our previous

I think we can use svelte props to make it reuseable

we can accept values like color, from our component As,

---
  import MakeItUnderlineAnimate from "./yourSvelteFile.svelte" 
---
<MakeItUnderlineAnimate color="#FF0060" client:visible >
    iAmUnderlined word
</MakeItUnderlineAnimate>

And Now use it in our svelte file Like,

  <script>
    import { onMount } from 'svelte';
    import { annotate } from 'rough-notation';
    export let color;
    let e;
    onMount(()=>{
      // a for annotation
      const a = annotate( e, {
        type:'underline',
        color: color,
        rtl:false,
        animate:true,
        padding:10,
        animationDuration:500,
        iterations:2,
      });
      a.show();
    });
  </script>
  <button bind:this={e}>
    <slot/>
  </button>

This will work perfectly fine .

So, it's bit longer but You might learn something new from this example .

But still astro is in it's starting stage So, bug are there But to make Astro best by each day you can make issue about there bugs at there github repo .

Checkout My personnel portfolio WEBSITE

DEV Community: Sukhpreet Singh